Fill the container

Use the SmsPopulate function to fill the container with objects that satisfy the criteria specified by the filters. The objects are represented as folders. The SmsPopulate function can retrieve folders in one of two modes: synchronous and asynchronous.

Synchronous

Your application waits until all folders that satisfy the filter criteria are retrieved and then goes on to the next line of code. To retrieve folders in synchronous mode, use POP_SYNC.

Asynchronous

Your application goes immediately to the next line of code while the SMS API engine retrieves all folders that satisfy the filter criteria. You can set additional flags that specify that the SMS API engine should set an event handle or post a message to a window each time a specified number of objects is retrieved.

For package containers and job containers, only synchronous mode is supported.

For containers that contain machine folders (site containers, site group containers, machine containers, and machine group containers), both modes are supported.

The SmsPopulate function takes three parameters:

• The handle to the container
• A DWORD that specifies the flags for the retrieval mode and the type of retrieval notification
• A pointer to a NOTIFY structure that the SMS API engine uses to report the type of retrieval specified by flags in the second parameter.

For detailed information on and examples of using asynchronous mode to populate machine, machine group, site, and site group containers, see Populating Containers in Asynchronous Mode.

The following example shows how to call SmsPopulate to populate a job container (note that a job container can be populated only in synchronous mode):

// Populate the job container with the job folders specified
// by the filters applied to the container. Retrieve folders
// synchronously.

HANDLE hContainer; //Handle to container.
stat = SmsOpenContainer (C_JOB, hConnect, &hContainer);
stat = SmsPopulate( hContainer, // Handle to container.
                    POP_SYNC,  // Job folders can only be
                               // retrieved in synchronous mode.
                    NULL       // NULL because synchronous 
                               // retrieval is used.
                  );