API: How do get a list of labels?

[ismangil]

Vault 3.1.1

Using the API, how do I get list of labels for a given file or folder, similar to right-click "Labels" in the GUI?

[dan]

Take a look at

ClientInstance.BeginLabelQuery(),

GetLabelQueryItems_Main()
or
ClientInstance.GetLabelQueryItems_Recursive()

followed by
ClientInstance.EndLabelQuery()

It works like history does (since there can be such a large number of labels coming back, we treat it like a query, so you are never stuck retrieving a very large number of possibly irrelevant labels). Check the command line client HISTORY command for an example of how it would work, and let us know if you get stuck.

[tk]

Dan,

I would like to write a small application that will browse a set of labels for a given folder to get the latest version based on that selection. In addition to this, I would like to parse out the comments for each file checked in after the selected label.

I see your notes above but I was hoping to find a better description of the object model (exmaple):

public void BeginLabelQuery(
string strItemPath,
long nObjID,
bool bGetRecursive,
bool bGetInherited,
bool bGetFileItems,
bool bGetFolderItems,
int nRowLimit,
out int nRowsRetrievedInherited,
out int nRowsRetrievedRecursive,
out string strQryToken
);

Is there any better documentation out there that describes the parameters for methods like this? I know this is largely unsupported but I was hoping for some new development.

I pulled down the historyquery already. Do you have any other samples? I would appreciate any help you can provide. Thanks!

tk

[jclausius]

tk:

The Command Line client source code has some decent examples. If you haven't already done so, you can download the code from the Client API

In the meantime, maybe a description would help. Due to the "virtualized" list, retrieving the labels of an object is a 3 step process.

1. Call BeginLabelQuery()
   
   The declaration void BeginLabelQuery(
   string strItemPath,
   long nObjID,
   bool bGetRecursive,
   bool bGetInherited,
   bool bGetFileItems,
   bool bGetFolderItems,
   int nRowLimit,
   out int nRowsRetrievedInherited,
   out int nRowsRetrievedRecursive,
   out string strQryToken
   );
   
   • strItemPath = the Repository's path to the item.
   • nObjID = the object ID at the path.
   • bGetRecursive = applies to folders - will retrieve labels that were applied to sub items as well as the main item in strItemPath.
   • bGetInherited = applies to labels applied to ancestor folders of strItemPath.
   • bGetFileItems = for recursive queries; this will include/exclude labels applied to sub-files.
   • bGetFolderItems = for recursive queries; this will include/exclude labels applied to sub-folders.
   • nRowLimit = number of labels to retrieve.
   • out nRowsRetrievedInherited = the number of rows retrieved from direct or inherited labels.
   • out nRowsRetrievedRecursive = the number of rows retrieved from direct or recursive labels.
   • out strQryToken = a token used to retrieve the results from the query.
2. Once you've successfully called BeginLabelQuery(), you then call GetLabelQueryItems_Main() or GetLabelQueryItems_Recursive() using the strQryToken. This will return an array of VaultLabelItemX.
3. Once you've retrieved the results, clean up by calling EndLabelQuery()