WSAAsyncGetProtoByNumber
The Windows Sockets
WSAAsyncGetProtoByNumber function gets protocol information corresponding to a protocol number
asynchronous version.
HANDLE WSAAsyncGetProtoByNumber (
HWND hWnd,
|
|
unsigned int wMsg,
|
|
int number,
|
|
char FAR * buf,
|
|
int buflen
|
|
);
|
|
Parameters
hWnd
[in] The handle of the window which should receive a message when the
asynchronous request completes.
wMsg
[in] The message to be received when the asynchronous request completes.
number
[in] The protocol number to be resolved, in host byte order.
buf
[out] A pointer to the data area to receive the protoent data. Note that this
must be larger than the size of a protoent structure. This is because the data
area supplied is used by Windows Sockets to contain not only a protoent
structure but any and all of the data which is referenced by members of the protoent
structure. It is recommended that you supply a buffer of MAXGETHOSTSTRUCT bytes.
buflen
[in] The size of data area
buf above.
Remarks
This function is an asynchronous version of
getprotobynumber, and is used to retrieve the protocol name and number corresponding to a
protocol number. Windows Sockets initiates the operation and returns to the caller
immediately, passing back an opaque "asynchronous task handle" which the
application can 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 can be any error as defined in
WINSOCK2.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 can reissue
the
WSAAsyncGetProtoByNumber function call with a buffer large enough to receive all the desired
information (that is, 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
WINSOCK2.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 Values
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,
WSAAsyncGetProtoByNumber returns a nonzero value of type HANDLE which is the asynchronous task handle
for the request (not to be confused with a Windows HTASK). 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,
WSAAsyncGetProtoByNumber returns a zero value, and a specific error number can be retrieved by calling
WSAGetLastError.
Comments
The buffer supplied to this function is used by Windows Sockets 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 WINSOCK2.H).
Error Codes
The following error codes can be set when an application window receives a
message. As described above, they can be extracted from the
lParam in the reply message using the WSAGETASYNCERROR macro.
WSAENETDOWN
| The network subsystem has failed.
|
WSAENOBUFS
| Insufficient buffer space is available.
|
WSAEFAULT
| buf is not in a valid part of the process address space.
|
WSAHOST_NOT_FOUND
| Authoritative Answer Protocol not found.
|
WSATRY_AGAIN
| Non-Authoritative Protocol not found, or server failure.
|
WSANO_RECOVERY
| Nonrecoverable errors, the protocols database is not accessible.
|
WSANO_DATA
| Valid name, no data record of requested type.
|
The following errors can occur at the time of the function call, and indicate
that the asynchronous operation could not be initiated.
WSANOTINITIALISED
| A successful WSAStartup must occur before using this function.
|
WSAENETDOWN
| The network subsystem has failed.
|
WSAEINPROGRESS
| A blocking Windows Sockets 1.1 call is in progress, or the service provider is
still processing a callback function.
|
WSAEWOULDBLOCK
| The asynchronous operation cannot be scheduled at this time due to resource or
other constraints within the Windows Sockets implementation.
|
See Also
getprotobynumber,
WSACancelAsyncRequest
- Software for developers
-
Delphi Components
.Net Components
Software for Android Developers
- More information resources
-
MegaDetailed.Net
Unix Manual Pages
Delphi Examples
- Databases for Amazon shops developers
-
Amazon Categories Database
Browse Nodes Database
