SmsGetFolderByID

The SmsGetFolderByID function retrieves the handle to the folder with the specified identifier from the specified parent folder.

SMS_STATUS SmsGetFolderByID(
  HANDLE hFolder,     // Handle to parent folder.
  DWORD fType,        // Type of folder.
  char *pszFolderID,  // Pointer to folder identifier.
  HANDLE *phSubFolder // Pointer to handle that will receive the 
                      // folder handle.
);
 

Parameters

hFolder

Specifies the handle to the parent folder from which to retrieve a folder with the specified identifier.

fType

Specifies the type of the folder whose handle you want to retrieve. See Folder Types. Note that your application must specify a specific folder type. F_ANY cannot be specified for this parameter.

pszFolderID

Specifies the folder's identifier. See the following remarks for descriptions of the identifiers for each type of folder.

phSubFolder

Receives the handle to the folder identified by pszFolderID.

Return Values

The SmsGetFolderByID 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 parent handle is not a valid folder handle.

SMS_FOLDER_ALREADY_DELETED

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

SMS_INVALID_FOLDER_TYPE

The folder type specified is not one of the subfolder types that may be contained in the specified folder.

SMS_NOT_FOUND

The folder with the specified identifier was not found.

Remarks

Note that your application can use only SmsGetNextFolder to retrieve top-level folders in a container. Top-level folders in a container can only be retrieved by sequence. The sequence of folders within a container is determined by the order in which the SMS API engine retrieved the folders from the site database. SmsGetFolderByID cannot be used to retrieve a top-level folder in a container.

The SmsGetFolderByID function retrieves the handle to the folder with the specified identifier. 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_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_PROGITEM

Program item identifier. For example, AUS00001.

F_SITE

Site code. For example, AUS.

F_WCL

Command name.