To access objects from a site database, your application must populate a container by using the SmsPopulate function.
Before a container is populated, your application can specify the criteria to use in selecting the objects to retrieve. Your application does this by applying filters to the container.
If your application does not set a filter on the container by using the SmsSetFilter function, SmsPopulate fills the container with folders that represent all objects (of the type supported by the container) in the site database. 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.
For containers that contain machine folders (site container, site group container, machine container, and machine group container), the SmsPopulate function can retrieve folders in one of two modes: synchronous or asynchronous. For package containers and job containers, only synchronous mode is supported. Note that there are some special issues to be addressed when using asynchronous retrieval for site containers and site group containers. For more detailed information, see Populating Containers in Asynchronous Mode.
After a container has been populated, your application can access the objects (which are represented as folders) and their properties. Note that folders retrieved by SmsPopulate represent the set of objects in the site database at the time when SmsPopulate was called by your application. Any objects added to the site database after SmsPopulate is called are not reflected in the list of folders within the container. Currently, containers cannot be refreshed. To get the latest information from the site database, your application must open and populate a new container and then access the information in the new container.
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.