The SmsPopulate function fills the container with objects from the site database.
SMS_STATUS SmsPopulate(
HANDLE hContainer, // Handle to container.
DWORD dwOptions, // Flags for retrieval mode and notification.
NOTIFY *pNotify // Pointer to NOTIFY structure for the
// retrieval notification.
);
For package containers and job containers, only synchronous mode is supported.
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:
Important An event is a type of synchronization object provided by the Win32 API. It is the responsibility of your application to create a valid event object and reset the event object by using the synchronization functions of the Win32 API. Given a handle to a valid event object through the NOTIFY structure, the SMS API engine sets the event to the signaled state when the specified number of folders have been retrieved.
To retrieve folders in asynchronous mode, set the POP_ASYNC flag.
If the POP_ASYNC and POP_EVENT flags are set for dwOptions, the SMS API engine sets the event specified by the hEvent member of pNotify structure to the signaled state. The SMS API engine sets an event handle to the signaled state each time a specified number of objects are retrieved and when all objects are retrieved. If the POP_ASYNC and POP_WINDOW flags are set for dwOptions, the SMS API engine posts the message specified by the uiMsg member of pNotify structure to the window specified by the hwnd member. The SMS API engine posts a message to a window each time a specified number of objects are retrieved and when all objects are retrieved.
Important Asynchronous retrieval can be used only on machine, machine group, site, and site group containers. Although the SmsPopulate function applies to containers, the asynchronous behavior goes into effect only when retrieving machine folders from their parent folders or containers. For machine containers, the asynchronous behavior is in effect when SmsPopulate is called, because machine folders are the top-level folder in the container.
However, the machine folders in a site container are lower-level folders contained within the domain folders within site folders. When your application uses asynchronous population on a site container, the asynchronous retrieval takes effect when your application accesses the folder containing the machine folders—that is, the domain folder. The site folders and the domain folders are not retrieved asynchronously. This means that your application should wait on an event only after machine retrieval in a domain folder or a machine container has been triggered—the event will never be set to the signaled state if no machines are retrieved, and the wait function (such as WaitForSingleObject) will time out.
In addition, when using asynchronous retrieval with events or window messages for site containers and site group containers, there are some special issues that need to be addressed (such as triggering machine retrieval in domain folders). For more detailed information, see Populating Containers in Asynchronous Mode.
If only the POP_ASYNC flag is set, SmsPopulate performs no notification.
If the POP_SYNC flag is specified for dwOptions, set this value to NULL.
This structure is only used if POP_ASYNC is specified in dwOptions. The dwFreq member specifies the frequency of retrieval notification. Each time the SMS API engine has retrieved the number of objects specified by dwFreq, it notifies your application by setting an event or by posting a message to a window. In addition, the SMS API engine notifies your application when all objects have been retrieved.
The type of notification depends on the flags set in the dwOptions parameter. If the POP_ASYNC and POP_EVENT flags are set for dwOptions, the SMS API engine sets the event specified by the hEvent member to the signaled state. If the POP_ASYNC and POP_WINDOW flags are set for dwOptions, the SMS API engine posts the message specified by the uiMsg member to the window specified by the hwnd member.
Note Your application is responsible for specifying a valid event handle for the hEvent member of the NOTIFY structure.
The SmsPopulate 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:
Note that an insufficient size for the tempdb on the SQL Server containing the site database can cause this error to occur.
To size the tempdb, you should allocate 2K per machine (that is, 2K for each inventoried object, including objects of all architectures such as Personal Computer, SMSEvent, UserGroups, and so on). The log device should be at least 20 percent of the size of the data device. For example, if you have 50,000 machines in your SMS database, you should allocate at least 100 MB total for the tempdb and at least 20 MB for the tempdb log.
—or—
An invalid window handle was specified in the hwnd member of the pNotify structure.
SmsPopulate initiates the retrieval process, which is carried out by the SMS API engine—SmsPopulate does not perform the actual retrieval itself. For asynchronous population, SmsPopulate returns immediately while the SMS API engine retrieves folders from the site database. The SMS API engine uses the information in the NOTIFY structure passed to it by SmsPopulate to post a window message or signal an event each time the specified number of folders is retrieved and when all folders are retrieved.
SmsPopulate retrieves the objects (which are represented as folders within the container) that satisfy the criteria specified by the filters applied to the container.
Filters can only be applied to containers. However, a filter may not take effect on the first level of folders within a container. Filters are only applied to folders that accept the filter's filter type.
For example, if an attribute filter (ATTRIBUTE_FILTER) is applied to a site container, the attribute filter has no effect on the set of domain folders or site folders that are retrieved when the site container is populated. However, the attribute filter will be applied to the machine folders within the domain folders. For each machine folder, the attribute filter determines which group folders are retrieved.
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.
Note Folders retrieved by SmsPopulate represent the set of objects in the site database at the time when SmsPopulate is 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.
For examples of asynchronous population, see Populating Containers in Asynchronous Mode.