Containers

The SMS API uses containers to hold objects retrieved from an SMS site database.

The SMS API accesses objects in a site database by retrieving information about those objects and storing that information in containers. There are different types of containers for different types of objects. For example, the C_PACKAGE container contains packages. To access an object in a site database, your application must open a container (which must support the type of object to be retrieved) by using the SmsOpenContainer function.

After your application has populated a container with objects from a site database, the application can access those objects and their properties. An application populates a container by using the SmsPopulate function.

Within a container, the instance of an object is represented as a folder. For example, a C_PACKAGE container can contain a set of folders that represent the packages in the current site's site database. The properties of an object are represented as subfolders or scalars within that object's folder. For example, a package folder has scalars that represent the package name, package identifier, and so on. In addition, a package folder can contain workstation command line folders, program item folders, and one inventory rules folder.

Before your application populates a container, it can set filters on the container. Filters specify the objects to retrieve from the site database and store in the container. If no filter is set for a container, all objects (that is, all objects of the type supported by the container) are returned when the container is populated. There are eight types of filters available. The types of filters that you can set are dependent on the container. For example, filters of type ARCHITECTURE_FILTER, SITELIMIT_FILTER, MACHINE_FILTER, GROUP_FILTER, and ATTRIBUTE_FILTER can be set on a machine container. For more information on creating and setting filters, see Filters.

After a container has been populated, the order of the folders within that particular container is fixed. Using the SmsGetNextFolder function, your application can access the folders in the container sequentially. SmsGetNextFolder returns the handle to the next folder in the list of folders within a container. Because SmsGetNextFolder reads folders sequentially, your application must explicitly reset the folder list to start at the beginning of the list again. When SmsGetNextFolder has reached the end of the folder list, it returns SMS_NO_MORE_DATA. Your application can use SmsRewind to start at the beginning of the folder list again. SmsRewind enables your application to iterate the folders again from the beginning of the folder list.

If a folder within a container has subfolders, your application can use SmsGetNextFolder to access those subfolders. Your application can also access a subfolder within a folder by the subfolder's identifier, by using the SmsGetFolderByID function. Note that top-level folders in a container can be retrieved only by using SmsGetNextFolder.

For more information about accessing containers, folders, and scalars, see General Steps for Using the SMS API to Manage SMS Objects.