WinAsyncAPPCEx()

This is an asynchronous entry point for all of the APPC verbs. Use this call to enable multiple sessions to be handled on the same thread.

Use this entry point if you want the application to be notified of completion through an event and your application requires the ability to cancel outstanding verbs; otherwise, use the APPC queue-level nonblocking entry point.

Syntax

HANDLE WINAPI WinAsyncAPPCEx(HANDLE handle,long vcb);

Parameters

handle
Handle of the event that the application will wait on.
vcb
Pointer to verb control block.

Returned Values

The return value specifies whether the asynchronous request was successful. If the function was successful, the actual return value is a handle. If the function was not successful, Personal Communications returns a 0.

Usage Notes

This verb is intended for use with WaitForMultipleObjects in the Win32® API.

APPC verbs that can block are as follows:
  • [MC_]ALLOCATE
  • CANCEL_CONVERSATION
  • [MC_]CONFIRM
  • [MC_]CONFIRMED
  • [MC_]DEALLOCATE
  • [MC_]FLUSH
  • [MC_]PREPARE_TO_RECEIVE
  • RECEIVE_ALLOCATE
  • [MC_]RECEIVE_AND_WAIT
  • [MC_]REQUEST_TO_SEND
  • [MC_]SEND_CONVERSATION
  • [MC_]SEND_DATA
  • [MC_]SEND_ERROR
  • TP_ENDED
  • TP_STARTED

This entry point does not support queue-level nonblocking. If the queue-level nonblocking flag AP_NON_BLOCKING is specified on the asynchronous interface, Personal Communications ignores it. When using the asynchronous entry point, an application can have only one outstanding function in progress on a conversation at a time. An attempt to initiate a second function results in the error code AP_CONV_BUSY.

The WinAsyncAPPCEx entry point permits the verb to be canceled, but does not support queue-level nonblocking. The APPC entry point supports queue-level nonblocking, but does not permit the application to cancel the verb. The exceptions to the previous paragraph are RECEIVE_AND_POST and RECEIVE_AND_WAIT. To enable full use to be made of the asynchronous support, Personal Communications alters asynchronously issued RECEIVE_AND_WAIT verbs to act like the RECEIVE_AND_POST verb. Specifically, while an asynchronous RECEIVE_AND_POST or RECEIVE_AND_WAIT is outstanding, an application can issue the following verbs on the same conversation:
  • REQUEST_TO_SEND
  • CANCEL_CONVERSATION
  • GET_TYPE
  • GET_ATTRIBUTES
  • TEST_RTS
  • DEALLOCATE (AP_ABEND_PROG, AP_ABEND_SVC, or AP_ABEND_TIMER)
  • SEND_ERROR
  • TP_ENDED

This enables an application, and in particular, a server application, to use an asynchronous RECEIVE_AND_WAIT to receive data. While the RECEIVE_AND_POST or RECEIVE_AND_WAIT is outstanding, the application can still use SEND_ERROR and REQUEST_TO_SEND.

When the asynchronous operation is complete, Personal Communications notifies the application by the signaling of the event. When the application receives the signal, it examines the primary return code and secondary return code for any error conditions.

See also: