Description
Get protocol information corresponding to a protocol name - asynchronous version.
#include <winsock.h>
HANDLE PASCAL FAR WSAAsyncGetProtoByName ( HWND hWnd, unsigned int wMsg, const char FAR * name, char FAR * buf, int buflen);
hWnd
Remarks
This function is an asynchronous version of getprotobyname(), and is used to retrieve the protocol name and number corresponding to a protocol name. The Windows Sockets implementation initiates the operation and returns to the caller immediately, passing back an asynchronous task handle which the application may use to identify the operation. When the operation is completed, the results (if any) are copied into the buffer provided by the caller and a message is sent to the application's window. When the asynchronous operation is complete the application's window hWnd receives message wMsg. The wParam argument contains the asynchronous task handle as returned by the original function call. The high 16 bits of lParam contain any error code. The error code may be any error as defined in winsock.h. An error code of zero indicates successful completion of the asynchronous operation. On successful completion, the buffer supplied to the original function call contains a protoent structure. To access the elements of this structure, the original buffer address should be cast to a protoent structure pointer and accessed as appropriate.
Note that if the error code is WSAENOBUFS, it indicates that the size of the buffer specified by buflen in the original call was too small to contain all the resultant information. In this case, the low 16 bits of lParam contain the size of buffer required to supply ALL the requisite information. If the application decides that the partial data is inadequate, it may reissue the WSAAsyncGetProtoByName() function call with a buffer large enough to receive all the desired information (i.e. no smaller than the low 16 bits of lParam).
The error code and buffer length should be extracted from the lParam using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in winsock.h as:
#define WSAGETASYNCERROR(lParam) HIWORD(lParam)#define WSAGETASYNCBUFLEN(lParam) LOWORD(lParam)
The use of these macros will maximize the portability of the source code for the application.
Return Value
The return value specifies whether or not the asynchronous operation was successfully initiated. Note that it does not imply success or failure of the operation itself. If the operation was successfully initiated, WSAAsyncGetProtoByName() returns a nonzero value of type HANDLE which is the asynchronous task handle for the request. This value can be used in two ways. It can be used to cancel the operation using WSACancelAsyncRequest(). It can also be used to match up asynchronous operations and completion messages, by examining the wParam message argument.
If the asynchronous operation could not be initiated, WSAAsyncGetProtoByName() returns a zero value, and a specific error number may be retrieved by calling WSAGetLastError().
Comments
The buffer supplied to this function is used by the Windows Sockets implementation to construct a protoent structure together with the contents of data areas referenced by members of the same protoent structure. To avoid the WSAENOBUFS error noted above, the application should provide a buffer of at least MAXGETHOSTSTRUCT bytes (as defined in winsock.h).
Notes For Windows Sockets Suppliers
It is the responsibility of the Windows Sockets implementation to ensure that messages are successfully posted to the application. If a PostMessage() operation fails, the Windows Sockets implementation must re-post that message as long as the window exists.
Windows Sockets suppliers should use the WSAMAKEASYNCREPLY macro when constructing the lParam in the message.
Error Codes
The following error codes may be set when an application window receives a message. As described above, they may be extracted from the lParam in the reply message using the WSAGETASYNCERROR macro.
WSAENETDOWN
The following errors may occur at the time of the function call, and indicate that the asynchronous operation could not be initiated.
WSANOTINITIALISED
See Also
getprotobyname(), WSACancelAsyncRequest()