Share via

WSAConnectByName (Compact 7)

  • Article

3/12/2014

This function establishes a connection to a specified host and port to allow for a quick connection to a network endpoint given a host name and port.

This function supports both IPv4 and IPv6 addresses.

Syntax

int  WSAConnectByName(
  SOCKET s,
    LPSTR nodename,
    LPSTR servicename,
    LPDWORD LocalAddressLength,
    LPSOCKADDR LocalAddress,
    LPDWORD RemoteAddressLength,
    LPSOCKADDR RemoteAddress,
    const struct timeval* time-out,
  LPWSAOVERLAPPED Reserved
);

Parameters

  • s
    [in] Descriptor identifying an unconnected socket
  • nodename
    NULL-terminated string that contains the name of the host or the IP address of the host on which to connect for IPv4 or IPv6
  • servicename
    A NULL-terminated string that contains the service name or destination port of the host on which to connect for IPv4 or IPv6. Legal values for the servicename parameter are listed in the following file: "%WINDIR%\system32\drivers\etc\services".
  • LocalAddressLength
    On input, a pointer to the size, in bytes, of the LocalAddress buffer provided by the caller. On output, a pointer to the size, in bytes, of the SOCKADDR for the local address stored in the LocalAddress buffer filled in by the system upon successful completion of the call
  • LocalAddress
    A pointer to the SOCKADDR structure that receives the local address of the connection. The size of the parameter is exactly the size returned in LocalAddressLength. This is the same information that would be returned by the getsockname (Windows Sockets) function. This parameter can be NULL. In this case,, the LocalAddressLength parameter is ignored.
  • RemoteAddressLength
    On input, a pointer to the size, in bytes, of the RemoteAddress buffer provided by the caller. On output, a pointer to the size, in bytes, of the SOCKADDR for the remote address stored in RemoteAddress buffer filled-in by the system upon successful completion of the call.
  • RemoteAddress
    A pointer to the SOCKADDR structure that receives the remote address of the connection. This is the same information that would be returned by the getpeername (Windows Sockets) function. This parameter can be NULL. In this case,, the RemoteAddressLength is ignored.
  • timeout
    The time, in milliseconds, to wait for a response from the remote application before aborting the call.
  • Reserved
    Reserved; set to NULL.

Return Value

If a connection is established, WSAConnectByName returns TRUE and the LocalAddress and RemoteAddress parameters are filled in if these buffers were supplied by the caller.

If the call fails, FALSE is returned. WSAGetLastError can then be called to retrieve extended error information.

Return Code Description

WSAEHOSTUNREACH

The host passed as the nodename parameter was unreachable

WSAEINVAL

An invalid parameter was passed to the function. The nodename or the servicename parameter must not be NULL. The Reserved parameter must be NULL.

WSAENOBUFS

Sufficient memory could not be allocated

WSAENOTSOCK

An invalid socket was passed to the function. The s parameter must not be INVALID_SOCKET or NULL.

WSAETIMEDOUT

A response from the remote application was not received before the timeout parameter was exceeded.

Remarks

WSAConnectByName is provided to enable quick and transparent connections to remote hosts on specific ports. It is compatible with both IPv6 and IPv4 versions.

To enable both IPv6 and IPv4 communications, use the following method:

  • The setsockopt (Windows Sockets) function must be called on a socket created for the AF_INET6 address family to disable the IPV6_V6ONLY socket option before calling WSAConnectByName. This is achieved by calling the setsockopt function on the socket with the level parameter set to IPPROTO_IPV6 (see IPPROTO_IPV6 Socket Options), the optname parameter set to IPV6_V6ONLY, and the optvalue parameter value set to zero.

WSAConnectByName has limitations: It works only for connection-oriented sockets, such as those of type SOCK_STREAM. The function does not support overlapped I/O or non-blocking behavior. WSAConnectByName will block even if the socket is in non-blocking mode.

WSAConnectByName does not support user-provided data during the establishment of a connection. This call does not support FLOWSPEC structures, either. If these features are required, WSAConnect must be used instead.

WSAConnectByName will consider only the Connection Manager connections that the calling application can use, thereby honoring Connection Manager policy. This drives the requirement into AFD to perform a name resolution query on a specific network interface and a connect() attempt on a specific network interface.

Note

WSAConnectByName uses the Connection Manager client API function named CmGetFirstAddr to invoke the per-interface name resolution.

If an application must bind to a specific local address or port, WSAConnectByName cannot be used because the socket parameter to WSAConnectByName must be an unbound socket.

The RemoteAddress and the LocalAddress parameters point to a SOCKADDR structure. This is a generic data type. When WSAConnectByName is called, it is expected that a socket address type that is specific to the network protocol or address family being used will actually be passed in these parameters. So for IPv4 addresses, a pointer to a sockaddr_in structure would be cast to a pointer to SOCKADDR as the RemoteAddress and LocalAddress parameters. For IPv6 addresses, a pointer to a sockaddr_in6 structure would be cast to a pointer to SOCKADDR as the RemoteAddress and LocalAddressparameters.

Example Code

Establish a connection by using WSAConnectByName:

Important

For readability, the following code example does not contain security checking or error handling. Do not use the following code in a production environment.

SOCKET
OpenAndConnect(LPWSTR NodeName, LPWSTR PortName) 
{
    SOCKET ConnSocket;
    int ipv6only = 0;
    int iResult;
    BOOL bSuccess;
    SOCKADDR_STORAGE LocalAddr = {0};
    SOCKADDR_STORAGE RemoteAddr = {0};
    DWORD dwLocalAddr = sizeof(LocalAddr);
    DWORD dwRemoteAddr = sizeof(RemoteAddr);
  
    ConnSocket = socket(AF_INET6, SOCK_STREAM, 0);
    if (ConnSocket == INVALID_SOCKET){
        return INVALID_SOCKET;
    }

    iResult = setsockopt(ConnSocket, IPPROTO_IPV6,
        IPV6_V6ONLY, (char*)&ipv6only, sizeof(ipv6only) );
    if (iResult == SOCKET_ERROR){
        Closesocket(ConnSocket);
        return INVALID_SOCKET;       
    }

    bSuccess = WSAConnectByName(ConnSocket, NodeName, 
            PortName, &dwLocalAddr,
            (SOCKADDR*)&LocalAddr,
            &dwRemoteAddr,
            (SOCKADDR*)&RemoteAddr,
            NULL,
            NULL);
    if (bSuccess){
        return ConnSocket;
    } else {
        return INVALID_SOCKET;
    }
}

See Also

Reference

Windows-Specific Extension Functions
getsockname (Windows Sockets)
getpeername (Windows Sockets)
WSAGetLastError
setsockopt (Windows Sockets)
IPPROTO_IPV6
WSAConnect
WSAConnectByList
sockaddr_in
sockaddr_in6