PURPOSE

AEWsetblockinghook - establish an application-specific blocking hook function

SYNOPSIS

#include <atmi.h>
int FARPROC far pascal AEWsetblockinghook(FARPROC)

DESCRIPTION

AEWsetblockinghook() is an "ATMI Extension for Windows" that allows a Windows task to install a new function which the ATMI networking software uses to implement blocking ATMI calls. It takes a pointer to the procedure instance address of the blocking function to be installed.

A default function, by which blocking ATMI calls are handled, is included. The function AEWsetblockinghook() gives the application the ability to execute its own function at "blocking" time in place of the default function. If called with a NULL pointer, the blocking hook function is reset to the default function.

When an application invokes a blocking ATMI operation, the operation is initiated and then a loop is entered which is equivalent to the following pseudocode:

for(;;) {
        execute operation in non-blocking mode
        if error
                break;
        if operation complete
                break;
        while(BlockingHook())
                ;
}

The default BlockingHook() function is equivalent to:

BOOL far pascal
win_default(void)
{
        MSG     msg;
        BOOL    ret;
        /* get the next message if any */
        if (ret = PeekMessage(&msg, NULL, 0, 0, PM_REMOVE)) {
                /* if we got one, process it */
                TranslateMessage(&msg);
                DispatchMessage(&msg);
        }
        /* TRUE if we got a message */
        return(ret);
}

The AEWsetblockinghook() function is provided to support those applications which require more complex message processing - for example, those employing the MDI (multiple document interface) model. It is not intended as a mechanism for performing general application functions. In particular, no ATMI functions may be issued from a custom blocking hook function. Note that the blocking hook function should return 0 to terminate the loop and non-zero to continue looping.

RETURN VALUES

AEWsetblockinghook() returns a pointer to the procedure-instance of the previously installed blocking function. The application or library that calls the AEWsetblockinghook() function should save this return value so that it can be restored if necessary. (If "nesting" is not important, the application may simply discard the value returned by AEWsetblockinghook() and eventually use AEWsetblockinghook(NULL) to restore the default mechanism.) AEWsetblockinghook() returns NULL on error and sets tperrno to indicate the error condition.

ERRORS

Under the following condition, AEWsetblockinghook() fails and sets tperrno to:

[TPEPROTO]: AEWsetblockinghook() was called while a blocking operation is in progress.

PORTABILITY

This interface is supported only in DOS Windows clients.

NOTICES

The blocking function is reset after tpterm(3c) is called by the application.