Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

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_INFOWstructure 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.

Error value Description

WSAENETDOWN

Network subsystem has failed.

WSAEAFNOSUPPORT

Specified address family is not supported.

WSAEINPROGRESS

Blocking Windows Sockets 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

Specified protocol is not supported.

WSAEPROTOTYPE

Specified protocol is the wrong type for this socket.

WSAESOCKTNOSUPPORT

Specified socket type is not supported in this address family.

WSAEINVAL

Parameter gspecified is not valid.

Remarks

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

The values for af, type,and protocolare those supplied by the application in the corresponding API functions socketor 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 afand type, because the ws2.dll considers these to be wildcard values. Also the value of manifest constant FROM_PROTOCOL_INFOmust be accepted for any of af, typeand protocol.This value indicates that the Windows Sockets 2 application needs to use the corresponding values from the indicated WSAPROTOCOL_INFOWstructure: ( iAddressFamily, iSocketType, iProtocol).

The dwFlagsparameter 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 utilize WSPSend, WSPSendTo, WSPRecv, WSPRecvFromand WSPIoctlfor overlapped I/O operations, which allow multiple operations to be initiated and in process simultaneously. All functions that allow overlapped operations also support nonoverlapped usage on an overlapped socket if the values for parameters related to overlapped operation are NULL.

WSA_FLAG_MULTIPOINT_C_ROOT

Indicates that the socket created will be a c_root in a multipoint session. Only allowed if a rooted control plane is indicated in the protocol's WSAPROTOCOL_INFOWstructure.

WSA_FLAG_MULTIPOINT_C_LEAF

Indicates that the socket created will be a c_leaf in a multicast session. Only allowed if XP1_SUPPORT_MULTIPOINT is indicated in the protocol's WSAPROTOCOL_INFOWstructure.

WSA_FLAG_MULTIPOINT_D_ROOT

Indicates that the socket created will be a d_root in a multipoint session. Only allowed if a rooted data plane is indicated in the protocol's WSAPROTOCOL_INFOWstructure.

WSA_FLAG_MULTIPOINT_D_LEAF

Indicates that the socket created will be a d_leaf in a multipoint session. Only allowed if XP1_SUPPORT_MULTIPOINT is indicated in the protocol's WSAPROTOCOL_INFOWstructure.

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_STREAMprovide 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 WSPConnectcall. Once connected, data can be transferred using WSPSendand WSPRecvcalls. When a session has been completed, a WSPCloseSocketmust 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 WSPSendToand WSPRecvFrom. If such a socket is connected by using WSPConnectto a specific peer, datagrams can be sent to that peer using WSPSendand can be received from (only) this peer using WSPRecv.

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

Shared Sockets

When a special WSAPROTOCOL_INFOWstructure (obtained through the WSPDuplicateSocketfunction and used to create additional descriptors for a shared socket) is passed as an input parameter to WSPSocket, the gand dwFlagsparameters are ignored.

Note:
The Windows Sockets service provider included in Windows Embedded CE does not support socket sharing. You can, however, create a customized service provider that supports shared sockets.

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 WSPSocketof the next layer in the provider chain. Some special considerations apply to this function's lpProtocolInfoparameter 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 WSPSocketis called, this layer must pass to the next layer a lpProtocolInfothat references the same unmodified WSAPROTOCOL_INFOWstructure 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_INFOWstructure should be referenced by the lpProtocolInfoparameter.

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_INFOWstructure through a layered sequence of other functions such as WSPAddressToString, WSPDuplicateSocket, WSPStartup, or WSPStringToAddress.

Requirements

Header ws2spi.h
Library Ws2.lib
Windows Embedded CE Windows CE .NET 4.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also