Bernd, can you describe why you need to do this, at a higher level? What is the user story? If it's for generating a change log, note that this is now supported in 3.0. See 59822: ANT task to generate text file with change set descriptions.

To list builds and get the snapshot for each, the APIs to use are as follows.

com.ibm.team.build.client.ClientFactory.getTeamBuildClient(ITeamRepository)
com.ibm.team.build.client.ITeamBuildClient.getBuildDefinition(String, IProgressMonitor) // lookup definition by id
com.ibm.team.build.internal.client.ITeamBuildRecordClient.getBuildResultRecords(IBuildDefinitionHandle[], BuildState[], String[], IProgressMonitor) // get builds for given definition(s)
com.ibm.team.build.client.ITeamBuildClient.getBuildResultContributions(IBuildResultHandle, String, IProgressMonitor) // get contributions of a given type

Use "buildSnapshot" as the contribution type, available as a constant: com.ibm.team.build.common.ScmConstants.EXTENDED_DATA_TYPE_ID_BUILD_SNAPSHOT

If a contribution is found, use
com.ibm.team.build.common.model.IBuildResultContribution.getExtendedContribution()

and cast to IBaselineSetHandle, then fetch the IBaselineSet item using the item manager as usual. This carries the name.

Note that personal builds do not carry a snapshot, so they should be skipped.

To get the ITeamBuildRecordClient, use:
ITeamBuildRecordClient buildClient = (ITeamBuildRecordClient) teamRepository.getClientLibrary(ITeamBuildRecordClient.class);

This is the general way to get a client library for a given repository. We should have a convenience for this on ClientFactory like we do for the others though.
I've filed a work item for this.

You could also have a look at the source code for the 'Changes' link in the build result editor, at /com.ibm.team.build.ui/src/com/ibm/team/build/internal/ui/scm/ChangeContributionProvider.java

It uses a custom query to get the previous non-personal build.

Regards,
Nick

If you give it the build result UUID, the generateChangeLog task lists the changes relative to the previous build (that had a snapshot, and ignoring personal builds).
In your scenario, is the only difference that you want to compare to the previous -successful- build, rather than just the previous build? Maybe we should just make that an option in the task, e.g. previousBuildStatus="OK". We'd probably also need to check the build status as well, e.g. previousBuildState="COMPLETED", if you want it to ignore abandoned builds.

I've filed 116227: Allow generateChangeLog Ant task to compare with previous successful build.

The 3rd argument to getBuildResultRecords is the list of properties to return for the results. Pass null to return them all. If you pass an empty string, you'll get no properties except for the basic ones like itemId and stateId, e.g. the result's label will come back unset. This is similar to the properties list passed to IItemManager.fetchPartialItem.

For getBuildResultContributions, the set of contribution types is open-ended, but see com.ibm.team.build.common.model.IBuildResultContribution for some well-known ones, e.g.:

    public static final String LOG_EXTENDED_CONTRIBUTION_ID = IBuildResultContribution.class.getName() + ".log";



    public static final String LINK_EXTENDED_CONTRIBUTION_ID = IBuildResultContribution.class.getName() + ".link"; 



    public static final String ARTIFACT_EXTENDED_CONTRIBUTION_ID = IBuildResultContribution.class.getName()

            + ".artifact";

ScmConstants also has:

    public static final String EXTENDED_DATA_TYPE_ID_BUILD_WORKSPACE = "buildWorkspace";