OnNotify method overview
The OnNotify method is called to notify an adapter about the progress of the map as related to the adapter.
MPIRC OnNotify (HMPIOBJ hAdapter, int
iEvent,int iParam,HMPIOBJ hConnection)Inputs
- hAdapter
- Adapter handle
- iEvent
- Event ID
- iParam
- [ignore this parameter]
- hConnection
- Connection handle
Outputs
None
Returns
Success status
| Notification | Description |
|---|---|
| MPIN_ADAPTER_GETSTART | Prior to any Get calls for the card |
| MPIN_ADAPTER_GETSTOP | After all Get calls for the card |
| MPIN_ADAPTER_PUTSTART | Prior to any Put calls for the card |
| MPIN_ADAPTER_PUTSTOP | After all Put calls for the card |
| MPIN_ADAPTER_LISTENSTART | Prior to any Listen calls for the card |
| MPIN_ADAPTER_LISTENSTOP | After all Listen calls for the card |
| MPIN_ADAPTER_LISTENABOR | Called to abort a non-polling listener |
| MPIN_ADAPTER_MAPABORT | When a map is cancelled by user action |
These entry points provide the opportunity for the adapter to initialize or clean up the Get, Put,or Listen method. For example, the adapter might need to query a queue to find out some properties about the queue. This would be done in the OnNotify (*_START) call. If it was done in the Get, Put, or Listen and these methods were called multiple times, unnecessary work would be performed repeatedly.
OnNotify is called with *_START prior to any Get, Put, or Listen, and is called with *_STOP after all Get, Put, or Listen calls. For example, if a map is executing multiple bursts and within each burst, Get is called multiple times to get multiple messages, there will be only one OnNotify call with MPIN_GET_START, prior to the first Get. Only after all bursts and all Gets within a burst, will OnNotify be called with MPIN_GET_STOP to allow the adapter to clean up.
If a user cancels a map execution, OnNotify will be called with MPIN_MAP_ABORT. The Get or Put methods should be aborted by the adapter as soon as possible after the notification.
The MPIN_ADAPTER_LISTENABORT notification is delivered only to adapters that have defined bListenerBlocks as TRUE in the vtable library. In this scenario, OnNotify is called on a separate thread from the Listen call. For all other notifications, the call is made on the connection thread.
When an adapter receives this notification, it should abort the Listen method using whatever mechanism or API that is supported by the adapter.