The WFSRegister and WFSDeregister functions (and their asynchronous counterparts) are used to register and deregister the window procedures which are to receive Windows messages when particular unsolicited, asynchronous events occur, either during request processing or at other times. In other words, they are used to enable or disable the reception of event notifications. By providing notifications of this type to applications, the requirement to poll for status is removed, and a simple method for implementing "monitoring" applications is provided. Each WFSRegister call specifies a service handle (hService), one or more event classes, and an application window handle (hWnd) which is to receive all the messages of the specified class(es). The corresponding SPI functions, WFPRegister and WFPDeregister, implement the API functions.
There are four classes of events:
For the first three of these event classes, if a class is being monitored and an event occurs in that class, a message is broadcast to every hWnd registered for that class, specifying the service identified by the hService handle. The events are generated when:
The EXECUTE_EVENTS class is different from the other three. These are events which occur as a normal part of processing an WFSExecute command. Examples include the need to interact with the user or operator to request an action such as inserting a passbook into a printer, “swiping” a mag stripe card, etc. A message generated by one of these events is sent only to the application that issued the WFSExecute that caused the event, even though other applications are registered for EXECUTE_EVENTS. Note that an application must explicitly register for these events; if it has not, and such an event occurs, the event is not deliverable and the WFSExecute completes normally.
The logic of WFSRegister is cumulative: for a given service the number of notification messages sent may be increased by specifying additional event classes. Since the XFS Manager does not keep track of what events the application is registered for and the logic of the register/deregister mechanism is cumulative, the service providers are responsible for implementing the logic of this process.
hr = WFSRegister( hService,USER_EVENTS|SERVICE_EVENTS,hWnd );
Note that services always monitor their resources, regardless of whether any application has registered for event monitoring or not. Issuing WFSRegister simply causes a service to send notifications to the service provider, which, in turn, sends notifications to one or more applications.
To communicate to the XFS Manager that it no longer wishes to receive messages in one or more event classes, an application can cancel any previous registration using the WFSDeregister function. The logic of WFSRegister and WFSDeregister is symmetric: the application can deregister one or more classes of events monitored for each window, by properly specifying them in the parameter list. To deregister completely (e.g., every event class for every window), an application uses NULL event class and window handle values in the parameter list.
Although the WFSDeregister takes effect immediately, it is possible that messages may be waiting in the application's message queue. A robust application must therefore be prepared to receive event messages even after deregistration.
Note that an event notification message always passes the information describing the event to an application by pointing to a WFSRESULT data structure. After the application has used the data in the structure, it must free the memory that the service provider allocated for the WFSRESULT data structure, using the WFSFreeResult function.