Listen method

The Listen method listens for events and returns when an event has occurred.

For example, a message has been received, a database update has occurred, and so on. In addition, should a connection become unusable, the Listen method should return a status indicating this.
MPIRC Listen (HMPIADAPT  
hAdapter,HCONNECTION  hConnection)

Inputs

hConnection
Connection handle

Outputs

None

Returns

MPIRC_BAD_CONNECTION
Connection failed other success status

In the vtable library, there is a bListenerBlocks configuration option that specifies whether the listener is interruptible. To be interruptible means that the function that the adapter calls to listen for an event must be able to be interrupted by a call from another thread.

Generally, unless the API provides a break call, the adapter is non-interruptible. If the adapter is non-interruptible, the Listen method should never execute for more than a few seconds. After being called, the adapter makes a call to its resource to discover new events. If, after a few seconds, no event has occurred, the Listen method should return.

Returning back to the Resource Manager allows the Resource Manager to determine whether to invoke Listen again, the most common scenario, or to shutdown the watch either because the application has asked for the watch to be deleted, or the application is in the process of shutting down. In the latter cases, the Resource Manager will invoke Disconnect to clean up the watch.

If the Listen method for the adapter is interrupted, it does not need not to return to the Resource Manager every few seconds if no event occurs, although it must return whenever an event occurs.

Instead, whenever a listener must be terminated by the Resource Manager, the OnNotify method will be called with a notification code of MPIN_ADAPTER_LISTENABORT on another thread from the listener. Within this call, the adapter should execute the break function on the listener's connection context to cause it to terminate and return control back to the Resource Manager.

If one or more events occur, the Listen method should return immediately, adding the event data to the message collection. For example, 
MyGetMessageID(&pMID);   
mpiPropertyGetObject(hAdapter, 
MPIP_ADAPTER_MSG_COLLECTION, 0, &hMsgColl);   
mpiMsgCollNewMsg(hMsgColl, pMID, strlen(pMID), 
NULL, 0, NULL, NULL);