NOTIFY

The NOTIFY structure contains information about retrieval notification for asynchronous population by the SmsPopulate function.

typedef struct _NOTIFY {
    DWORD dwFreq;
    HANDLE hEvent;
    HWND hwnd;
    UINT uiMsg;
} NOTIFY;

SmsPopulate uses this structure only if POP_ASYNC is specified in dwOptions. Event notification is enabled when the POP_ASYNC and POP_EVENT flags are set for dwOptions. Window notification is enabled when the POP_ASYNC and POP_WINDOW flags are set for dwOptions.

Members

dwFreq

Specifies frequency at which the SMS API engine should set an event handle or post a message to a window. 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 of SmsPopulate.

If dwFreq is set to zero, the default frequency of 500 is used.

hEvent

Specifies the handle to the event object to be set by the SMS API engine each time the number of objects specified by dwFreq is retrieved.

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.

If the POP_EVENT flag is set for dwOptions, the SMS API engine sets the event specified by the hEvent member to the signaled state.

hwnd

Specifies the handle to the window to which the SMS API engine should post a message each time the number of objects specified by dwFreq is retrieved. The message is specified by the uiMsg member.

If the POP_WINDOW flag is set for dwOptions, the SMS API engine posts the message specified by the uiMsg member to the window specified by hwnd.

uiMsg

Specifies the message that the SMS API engine should post to a window each time the number of objects specified by dwFreq is retrieved. The window is specified by the hwnd member.

If the POP_WINDOW flag is set for dwOptions, the SMS API engine posts the message specified by uiMsg to the window specified by hwnd.

Remarks

Note that SmsPopulate performs asynchronous population and retrieval notification only for containers that contain machine folders (site container, site group container, machine container, and machine group container).

In addition, SmsPopulate initiates the retrieval process, which is carried out by the SMS API engine. 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.

Important Asynchronous retrieval can only be used 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 that are contained within the domain folders within site folders. When your application uses asynchronous population on a site container, the asynchronous retrieval takes effect when it 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 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.