WSPSocket (Compact 2013)

3/26/2014

This function creates a socket.

Syntax

SOCKET WSPSocket(
  int af,
  int type,
  int protocol,
  LPWSAPROTOCOL_INFOW lpProtocolInfo,
  GROUP g,
  DWORD dwFlags,
  LPINT lpErrno 
);

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_INFOW structure that defines the characteristics of the socket to be created.

• g
  [in] Reserved.

• dwFlags
  Socket attribute specification.

• lpErrno
  [out] Pointer to the error code.

Return Value

If no error occurs, this function returns a descriptor referencing the new socket. Otherwise, a value of INVALID_SOCKET is returned, and a specific error code is available in lpErrno.

The following table shows the possible error codes.

Remarks

This function causes a socket descriptor and any related resources to be allocated. By default, the created socket will not have the overlapped attribute. For nonfile-system Windows Sockets providers, WPUCreateSocketHandle must be used to acquire a unique socket descriptor from the ws2.dll prior to returning from this function.

The values for af, type, and protocol are those supplied by the application in the corresponding API functions socket or WSASocket. A service provider is free to ignore or pay attention to any or all of these values as is appropriate for the particular protocol. However, the provider must be willing to accept the value of zero for af and type, because the ws2.dll considers these to be wildcard values. Also the value of manifest constant FROM_PROTOCOL_INFO must be accepted for any of af, type and protocol. This value indicates that the Windows Sockets 2 application needs to use the corresponding values from the indicated WSAPROTOCOL_INFOW structure: (iAddressFamily, iSocketType, iProtocol).

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.

For multipoint sockets, exactly one of WSA_FLAG_MULTIPOINT_C_ROOT or WSA_FLAG_MULTIPOINT_C_LEAF must be specified, and exactly one of WSA_FLAG_MULTIPOINT_D_ROOT or WSA_FLAG_MULTIPOINT_D_LEAF 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 WSPConnect call. Once connected, data can be transferred using WSPSend and WSPRecv calls. When a session has been completed, a WSPCloseSocket 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 sending and receiving of datagrams to and from arbitrary peers using WSPSendTo and WSPRecvFrom. If such a socket is connected by using WSPConnect to a specific peer, datagrams can be sent to that peer using WSPSend and can be received from (only) this peer using WSPRecv.

Support for sockets with type SOCK RAW is not required but service providers are encouraged to support raw sockets whenever it makes sense to do so.

Shared Sockets

When a special WSAPROTOCOL_INFOW structure (obtained through the WSPDuplicateSocket function and used to create additional descriptors for a shared socket) is passed as an input parameter to WSPSocket, the g and dwFlags parameters are ignored.

Layered Service Provider Considerations

A layered service provider supplies an implementation of this function, but it is also a client of this function if and when it calls WSPSocket of the next layer in the provider chain. Some special considerations apply to this function's lpProtocolInfo parameter as it is propagated down through the layers of the provider chain.

If the next layer in the provider chain is another layer then when the next layer's WSPSocket is called, this layer must pass to the next layer a lpProtocolInfo that references the same unmodified WSAPROTOCOL_INFOW structure with the same unmodified chain information. However, if the next layer is the base protocol (that is, the last element in the chain), this layer performs a substitution when calling the base provider's WSPSocket. In this case, the base provider's WSAPROTOCOL_INFOW structure should be referenced by the lpProtocolInfo parameter.

One vital benefit of this policy is that base service providers do not have to be aware of provider chains.

This same propagation policy applies when propagating a WSAPROTOCOL_INFOW structure through a layered sequence of other functions such as WSPAddressToString, WSPDuplicateSocket, WSPStartup, or WSPStringToAddress.

Requirements

See Also

Reference

Winsock SPI Functions
WSPAccept
WSPBind
WSPConnect
WSPGetSockName
WSPGetSockOpt
WSPSetSockOpt
WSPListen
WSPRecv
WSPRecvFrom
WSPSend
WSPSendTo
WSPShutdown
WSPIoctl
WPUCreateSocketHandle