WSASocket

  • Article

This function creates a socket that is bound to a specific transport service provider.

SOCKET WSASocket(
  int af,
  int type,
  int protocol,
  LPWSAPROTOCOL_INFO lpProtocolInfo,
  GROUP g,
  DWORD dwFlags
);

Parameters

  • af
    [in] Address family specification.
  • type
    [in] Type specification for the new socket.
  • protocol
    [in] Protocol to be used with the socket that is specific to the indicated address family.
  • lpProtocolInfo
    [in] Pointer to a WSAPROTOCOL_INFO structure that defines the characteristics of the socket to be created. For more information about WSAPROTOCOL_INFO, see Remarks.
  • g
    [in] Reserved.
  • dwFlags
    [in] Flag that specifies the socket attribute.

Return Values

If no error occurs, this function returns a descriptor referencing the new socket. If an error occurs, a value of INVALID_SOCKET is returned, and a specific error code can be retrieved by calling WSAGetLastError.

Note   This error code description is Microsoft-specific. The following table shows a list of possible error codes.

Error code Description
WSANOTINITIALISED A successful WSAStartup call must occur before using this function.
WSAENETDOWN The network subsystem has failed.
WSAEAFNOSUPPORT The specified address family is not supported.
WSAEINPROGRESS A blocking Winsock call is in progress, or the service provider is still processing a callback function.
WSAEMFILE No more socket descriptors are available.
WSAENOBUFS No buffer space is available. The socket cannot be created.
WSAEPROTONOSUPPORT The specified protocol is not supported.
WSAEPROTOTYPE The specified protocol is the wrong type for this socket.
WSAESOCKTNOSUPPORT The specified socket type is not supported in this address family.
WSAEINVAL This value is true for any of the following conditions:
  • The parameter g specified is not valid.
  • The WSAPROTOCOL_INFO structure that lpProtocolInfo points to is incomplete, the contents are invalid, or the WSAPROTOCOL_INFO structure has already been used in an earlier duplicate socket operation.
  • The values specified for members of the socket triple <af, type, and protocol> are individually supported, but the given combination is not.
WSAEFAULT The lpProtocolInfo argument is not in a valid part of the process address space.
WSAINVALIDPROVIDER The service provider returned a version other than 2.2.
WSAINVALIDPROCTABLE The service provider returned an invalid or incomplete procedure table to the WSAStartup.

Remarks

This function causes a socket descriptor and any related resources to be allocated and associated with a transport service provider. By default, the socket will not have an overlapped attribute. If lpProtocolInfo is NULL, ws2.dll uses the first three parameters (af, type, and protocol) to determine which service provider is used by selecting the first transport provider able to support the stipulated address family, socket type, and protocol values. If the lpProtocolInfo is not NULL, the socket will be bound to the provider associated with the indicated WSAPROTOCOL_INFO structure. In this instance, the application can supply the manifest constant FROM_PROTOCOL_INFO as the value for any of af, type, or protocol. This indicates that the corresponding values from the indicated WSAPROTOCOL_INFO structure (iAddressFamily, iSocketType, and iProtocol) are to be assumed. In any case, the values supplied for af, type, and protocol are supplied unmodified to the transport service provider.

In Windows CE and Windows NT, the Winsock layer examines only the dwCatalogEntryId member of the WSAPROTOCOL_INFO structure to determine which provider should be used. Thus, if lpProtocolInfo is not NULL, the CatalogEntryId member of the WSAPROTOCOL_INFO structure MUST be set to the desired provider's catalog id. However, because the structure is passed in its entirety to the underlying provider, the provider itself may make use of other info in that structure.

When selecting a protocol and its supporting service provider based on af, type, and protocol, this procedure will only choose a base protocol or a protocol chain, not a protocol layer by itself. Unchained protocol layers are not considered to have partial matches on type or af either. That is, they do not lead to an error code of WSAEAFNOSUPPORT or WSAEPROTONOSUPPORT, if no suitable protocol is found.

Note   The manifest constant AF_UNSPEC continues to be defined in the header file, but its use is strongly discouraged because this can cause ambiguity in interpreting the value of the protocol parameter.

The dwFlags parameter can be used to specify the attributes of the socket by using the bitwise OR operator with specific flags. The following table shows these flags.

Flag Description
WSA_FLAG_ OVERLAPPED This flag causes an overlapped socket to be created. Overlapped sockets can use WSASend, WSASendTo, WSARecv, WSARecvFrom, and WSAIoctl for overlapped I/O operations, which allow multiple operations to be initiated and in progress simultaneously. All functions that allow overlapped operation also support nonoverlapped usage on an overlapped socket if the values for parameters related to overlapped operations are NULL.
WSA_FLAG_ MULTIPOINT_C_ROOT Indicates that the socket created will be a c_root in a multipoint session. This is only allowed if a rooted control plane is indicated in the protocol's WSAPROTOCOL_INFO structure.
WSA_FLAG_ MULTIPOINT_C_LEAF Indicates that the socket created will be a c_leaf in a multicast session. This is only allowed if XP1_SUPPORT_MULTIPOINT is indicated in the protocol's WSAPROTOCOL_INFO structure.
WSA_FLAG_ MULTIPOINT_D_ROOT Indicates that the socket created will be a d_root in a multipoint session. This is only allowed if a rooted data plane is indicated in the protocol's WSAPROTOCOL_INFO structure. Refer to Multipoint and Multicast Semantics for additional information.
WSA_FLAG_ MULTIPOINT_D_LEAF Indicates that the socket created will be a d_leaf in a multipoint session. This is only allowed if XP1_SUPPORT_MULTIPOINT is indicated in the protocol's WSAPROTOCOL_INFO structure.

Important   For multipoint sockets, exactly one of the WSA_FLAG_MULTIPOINT_C_ROOT or WSA_FLAG_MULTIPOINT_C_LEAF flags must be specified, and exactly one of the WSA_FLAG_MULTIPOINT_D_ROOT or WSA_FLAG_MULTIPOINT_D_LEAF flags must be specified.

Connection-oriented sockets such as SOCK_STREAM provide full-duplex connections and must be in a connected state before any data can be sent or received on them. A connection to another socket is created with a connect (Windows Sockets)/WSAConnect call. Once connected, data can be transferred using send/WSASend and recv/WSARecv calls. When a session has been completed, a closesocket call must be performed.

The communications protocols used to implement a reliable, connection-oriented socket ensure that data is not lost or duplicated. If data for which the peer protocol has buffer space cannot be successfully transmitted within a reasonable length of time, the connection is considered broken and subsequent calls will fail with the error code set to WSAETIMEDOUT.

Connectionless message-oriented sockets allow the sending and receiving of datagrams to and from arbitrary peers using sendto/WSASendTo and recvfrom/WSARecvFrom. If such a socket is connected to a specific peer, datagrams can be sent to that peer using send/WSASend and can be received from (only) this peer using recv/WSARecv.

Support for the sockets with type RAW is not required, but service providers are encouraged to support raw sockets whenever possible.

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: Winsock2.h.
Link Library: Ws2.lib.

See Also

accept (Windows Sockets) | bind (Windows Sockets) | closesocket | connect (Windows Sockets) | getsockname (Windows Sockets) | getsockopt (Windows Sockets) | ioctlsocket | listen | recv | recvfrom | select | send | sendto | setsockopt (Windows Sockets) | shutdown | WSAConnect | WSAGetLastError | WSAIoctl | WSARecv | WSARecvFrom | WSASend | WSASendTo | WSAStartup

 Last updated on Saturday, April 10, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.