SmsOpenContainer

The SmsOpenContainer function opens a container for the type of object that you want to access in the site database.

SMS_STATUS SmsOpenContainer(
  DWORD cType,         // Type of container.
  HANDLE hConnection,  // Handle to database connection.
  HANDLE *phContainer  // Pointer to the handle that will receive 
                       // the pointer to the new container.
);
 

Parameters

cType

Specifies the type of container to open. See Container types.

hConnection

Specifies the handle to the database connection. A database connection is established using SmsDataSourceConnect.

phContainer

Points to the handle that is assigned the handle to the container. You use the handle to manage the container.

Return Values

The SmsOpenContainer 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 connection handle is not valid.

SMS_INVALID_CONTAINER_ID

An unknown container type was specified.

Remarks

Note that you can open multiple containers. For example, you could open two job containers to handle two types of job folders independently—one with a filter set to get Run Command On Workstation job folders (F_INSTALLJOB), and another container with a filter set to get Share Package On Server job folders (F_SRVINSTALL).

After your application uses the SmsOpenContainer function to open a container, the container is empty, that is, it contains no folders. Your application must use the SmsPopulate function to fill the container with objects from the site database. Before your application calls the SmsPopulate function, it can apply filters that specify criteria for retrieving objects (which are represented as folders within the container) from the database. Your application can create filters by using the SmsCreateFilter function, set tokens for the filter by using the SmsAddToken function, and apply the filter to the container by using the SmsSetFilter function. After applying filters to a container, your application must use the SmsPopulate function to query the site database for folders that meet the criteria set by the filters applied to the container. If no filters are applied to a container, all objects of the type supported by the container are retrieved by SmsPopulate.

After populating a container, your application can access the folders by using the SmsGetNextFolder function. For subfolders within a folder, SmsGetFolderByID can also be used to retrieve subfolders. Note that SmsGetFolderByID cannot be used to retrieve a top-level folder in a container.

After your application has finished using a container, it should free the memory used by the container by calling the SmsCloseContainer function.

If your application needs to open a filter container, it must call the SmsOpenFilterContainer function to open a filter container.

See Also

SmsDataSourceConnect, SmsPopulate, SmsCreateFilter, SmsSetFilter, SmsSetFilter, SmsGetNextFolder, SmsGetFolderByID, SmsCloseContainer, SmsOpenFilterContainer