WinAsyncAPPC()

This is an asynchronous entry point for all of the APPC verbs. An application uses this entry point if it chooses to be notified of completion through a Windows® message. Personal Communications and Communications Server provide this entry point for compatibility with existing applications.

Syntax

HANDLE WINAPI WinAsyncAPPC(HWND hWnd,long vcb)

Parameters

hwnd
Window handle to receive completion message.
vcb
Pointer to verb control block.

Returned Values

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

Usage Notes

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_]RECEIVE_EXPEDITED_DATA
  • [MC_]REQUEST_TO_SEND
  • [MC_]SEND_CONVERSATION
  • [MC_]SEND DATA
  • [MC_]SEND_ERROR
  • [MC_]SEND_EXPEDITED_DATA
  • TP_ENDED
  • TP_STARTED

The WinAsyncAPPC 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.

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. If an application needs to be notified of asynchronous completion through an event handle, it can use either the WinAsyncAPPCEx or APPC entry point. 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, such as a server, 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, the application's window hWnd receives the message returned by RegisterWindowMessage with WinAsyncAPPC as the input string. The wParam argument contains the asynchronous task handle returned by the original function call. The IParam argument contains the original VCB pointer and can be used to determine the final return code.

WinAPPCCancelAsyncRequest permits an application to cancel any asynchronous APPC action, but terminates the related conversation or transaction program as appropriate. Any outstanding operations return with AP_CANCELLED as the return code.

If the function returns successfully, Personal Communications posts a WinAsyncAPPC() message to the application when the operation completes or the conversation is canceled.

See also: