SmsGetFolderID

The SmsGetFolderID function retrieves the identifier of the folder specified by the folder handle.

SMS_STATUS SmsGetFolderID(
  HANDLE hFolder,    // Handle to folder.
  char *pszFolderID  // Pointer to buffer to receive the folder 
                     // identifier.
);
 

Parameters

hFolder

Specifies the handle to the folder whose identifier you want to retrieve.

pszFolderID

Points to the buffer that will receive the folder's identifier. Your application is responsible for ensuring that this buffer is large enough. If you are unsure of the correct buffer size, use SMS_DATA_BUFF_SIZE, which is the largest string size that SMS can currently store.

Return Values

The SmsGetFolderID function returns a status code SMS_STATUS. If successful, the function returns a status of SMS_OK. Otherwise, it returns one of the following manifest constants:

SMS_INVALID_HANDLE

The specified folder handle is not a valid folder handle.

SMS_FOLDER_ALREADY_DELETED

An action was attempted on a folder that has already been deleted.

SMS_NEW_FOLDER

The specified folder has only been created using the SmsCreateFolder function. No identifier value has been assigned to the folder yet. A folder is assigned an identifier after it is committed to the site database, using SmsCommitFolder.

Remarks

For the folder specified by the hFolder parameter, the SmsGetFolderID function returns the identifier for the folder in the character string specified by the pszFolderID parameter. The nature of the identifier depends on the type of folder:

F_DOMAIN

Domain name. For example, TIMDOMAIN.

F_GROUP

Group class name. The identifier has the form organization|class name|version.

F_INSTALLJOB

Job identifier. For example, AUS00001.

F_INVENTORY

An inventory rules folder always uses "Inventory rules" as the identifier.

F_MACHINE

For objects with the Personal Computer architecture, the identifier has the form site|domain|name. For objects with other architectures, the identifier is the string form of an integer.

F_MACHINEGROUP

Machine group name. For example, Leased Servers.

F_PACKAGE

Package identifier. For example, AUS00001.

F_PROGITEM

Program item identifier. For example, AUS00001.

F_REMPKGJOB

Job identifier. For example, AUS00001.

F_SITE

Site code. For example, AUS.

F_SITEGROUP

Site group name. For example, Europe Sites.

F_SRVINSTALLJOB

Job identifier. For example, AUS00001.

F_SYSTEMJOB

Job identifier. For example, AUS00001.

F_WCL

Command name.

Note that the identifiers for most new folders are available after they have been committed to the site database with SmsCommitFolder. If a new folder has been created using SmsCreateFolder or linked using SmsLinkFolder but has not been committed, SmsGetFolderID returns a status of SMS_NEW_FOLDER.

However, new workstation command line folders (F_WCL) and program item folders (F_PROGITEM) require some extra steps before their identifiers are available. For a new workstation command line folder, the identifier is available after the Name scalar is set for the folder (the Name scalar is used as the identifier) and after the folder has been linked and committed. For a new program item folder, the identifier is available after the folder itself and its parent folder have been linked and committed.