Export (0) Print
Expand All
Expand Minimize

WSAAsyncGetProtoByName function

The WSAAsyncGetProtoByName function asynchronously retrieves protocol information that corresponds to a protocol name.

Syntax


HANDLE WSAAsyncGetProtoByName(
  _In_   HWND hWnd,
  _In_   unsigned int wMsg,
  _In_   const char *name,
  _Out_  char *buf,
  _Out_  int buflen
);

Parameters

hWnd [in]

Handle of the window that will receive a message when the asynchronous request completes.

wMsg [in]

Message to be received when the asynchronous request completes.

name [in]

Pointer to the null-terminated protocol name to be resolved.

buf [out]

Pointer to the data area to receive the protoent data. The data area must be larger than the size of a protoent structure because the data area is used by Windows Sockets to contain a protoent structure and all of the data that is referenced by members of the protoent structure. A buffer of MAXGETHOSTSTRUCT bytes is recommended.

buflen [out]

Size of data area for the buf parameter, in bytes.

Return value

The return value specifies whether or not the asynchronous operation was successfully initiated. It does not imply success or failure of the operation itself.

If no error occurs, WSAAsyncGetProtoByName returns a nonzero value of type HANDLE that 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, or it can be used to match up asynchronous operations and completion messages, by examining the wParam message parameter.

If the asynchronous operation could not be initiated, WSAAsyncGetProtoByName returns a zero value, and a specific error number can be retrieved by calling WSAGetLastError.

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.

Error codeMeaning
WSAENETDOWN

The network subsystem has failed.

WSAENOBUFS

Insufficient buffer space is available.

WSAEFAULT

The name or buf parameter is not in a valid part of the process address space.

WSAHOST_NOT_FOUND

Authoritative answer protocol not found.

WSATRY_AGAIN

A nonauthoritative 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.

Error codeMeaning
WSANOTINITIALISEDA successful WSAStartup call must occur before using this function.
WSAENETDOWNThe network subsystem has failed.
WSAEINPROGRESSA blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAEWOULDBLOCKThe asynchronous operation cannot be scheduled at this time due to resource or other constraints within the Windows Sockets implementation.

 

Remarks

The WSAAsyncGetProtoByName function is an asynchronous version of getprotobyname. It is used to retrieve the protocol name and number from the Windows Sockets database corresponding to a given protocol name. Windows Sockets initiates the operation and returns to the caller immediately, passing back an opaque, asynchronous task handle that 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 has completed, the application window indicated by the hWnd parameter receives message in the wMsg parameter. The wParam parameter 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 specified to the original function call contains a protoent structure. To access the members of this structure, the original buffer address should be cast to a protoent structure pointer and accessed as appropriate.

If the error code is WSAENOBUFS, the size of the buffer specified by buflen in the original call was too small to contain all the resulting 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 WSAAsyncGetProtoByName 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 buffer specified 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).

The error code and buffer length should be extracted from the lParam using the macros WSAGETASYNCERROR and WSAGETASYNCBUFLEN, defined in Winsock2.h as:


#include <windows.h>

#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)
#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)


The use of these macros will maximize the portability of the source code for the application.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Winsock2.h

Library

Ws2_32.lib

DLL

Ws2_32.dll

See also

Winsock Reference
Winsock Functions
getprotobyname
WSACancelAsyncRequest

 

 

Community Additions

ADD
Show:
© 2014 Microsoft