Windows* Sockets 2 Application Programming Interface An Interface for Transparent Network Programming Under Microsoft Windowstm revision 2 August 7, 1997
Download 1.64 Mb.
|
- Navigate this page:
- IN GROUP
- Remarks
- Note
- WSASend() , WSASendTo() , WSARecv() , WSARecvFrom() and WSAIoctl()
- Important note
- WSADuplicateSocket()
- WSAGetLastError(). Error Codes
- See Also accept() , bind() , connect() , getsockname() , getsockopt() , setsockopt() , listen() , recv() , recvfrom() , select()
122 WSASocket()Description Create a socket which is bound to a specific transport service provider, optionally create and/or join a socket group. #include SOCKET WSAAPI WSASocket ( IN int af, IN int type, IN int protocol, IN LPWSAPROTOCOL_INFO lpProtocolInfo, IN GROUP g, IN DWORD dwFlags ); af An address family specification. type A type specification for the new socket. protocol A particular protocol to be used with the socket which is specific to the indicated address family. lpProtocolInfo A pointer to a WSAPROTOCOL_INFO struct that defines the characteristics of the socket to be created. g Reserved for future use with socket groups: The identifier of the socket group. dwFlags The socket attribute specification. Remarks This function causes a socket descriptor and any related resources to be allocated and associated with a transport service provider. By default, the created socket will not have the overlapped attribute. If lpProtocolInfo is NULL, the WinSock 2 DLL uses the first three parameters (af, type, 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 struct. In this instance, the application may 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 struct (iAddressFamily, iSocketType, iProtocol) are to be assumed. In any case, the values supplied for af, type and protocol are supplied unmodified to the transport service provider via the corresponding parameters to the WSPSocket() function in the SPI. 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, as this may cause ambiguity in interpreting the value of the protocol parameter. Reserved for future use with socket groups: Parameter g is used to indicate the appropriate actions on socket groups: if g is an existing socket group ID, join the new socket to this group, provided all the requirements set by this group are met; or if g = SG_UNCONSTRAINED_GROUP, create an unconstrained socket group and have the new socket be the first member; or if g = SG_CONSTRAINED_GROUP, create a constrained socket group and have the new socket be the first member; or if g = zero, no group operation is performed For unconstrained groups, any set of sockets may be grouped together as long as they are supported by a single service provider. A constrained socket group may consist only of connection-oriented sockets, and requires that connections on all grouped sockets be to the same address on the same host. For newly created socket groups, the new group ID can be retrieved by using getsockopt() with option SO_GROUP_ID, if this operation completes successfully. A socket group and its associated ID remain valid until the last socket belonging to this socket group is closed. Socket group IDs are unique across all processes for a given service provider. The dwFlags parameter may be used to specify the attributes of the socket by or-ing any of the following Flags: Flag Meaning WSA_FLAG_OVERLAPPED This flag causes an overlapped socket to be created. Overlapped sockets may utilize WSASend(), WSASendTo(), WSARecv(), WSARecvFrom() and WSAIoctl() for overlapped I/O operations, which allows multiple these operations to be initiated and in progress simultaneously. All functions that allow overlapped operation (WSASend(), WSARecv(),WSASendTo(), WSARecvFrom(), WSAIoctl()) also support non-overlapped 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_INFO struct. Refer to Appendix B. Multipoint and Multicast Semantics for additional information. 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_INFO struct. Refer to Appendix B. Multipoint and Multicast Semantics for additional information. 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_INFO struct. Refer to Appendix B. 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. Only allowed if XP1_SUPPORT_MULTIPOINT is indicated in the protocol’s WSAPROTOCOL_INFO struct. Refer to Appendix B. Multipoint and Multicast Semantics for additional information. Important note: 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. Refer to Appendix B. Multipoint and Multicast Semantics for additional information. Connection-oriented sockets such as SOCK_STREAM provide full-duplex connections, and must be in a connected state before any data may be sent or received on them. A connection to another socket is created with a connect()/WSAConnect() call. Once connected, data may be transferred using send()/WSASend() and recv()/WSARecv() calls. When a session has been completed, a closesocket() 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 sendto()/WSASendTo() and recvfrom()/WSARecvFrom(). If such a socket is connect()ed to a specific peer, datagrams may be sent to that peer using send()/WSASend() and may be received from (only) this peer using recv()/WSARecv(). Support for sockets with type 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_INFO struct (obtained via the WSADuplicateSocket() function and used to create additional descriptors for a shared socket) is passed as an input parameter to WSASocket(), the g and dwFlags parameters are ignored. Such a WSAPROTOCOL_INFO struct may only be used once, otherwise the error code WSAEINVAL will result. Return Value If no error occurs, WSASocket() returns a descriptor referencing the new socket. Otherwise, a value of INVALID_SOCKET is returned, and a specific error code may be retrieved by calling WSAGetLastError(). Error Codes WSANOTINITIALISED A successful WSAStartup() must occur before using this API. WSAENETDOWN The network subsystem has failed. WSAEAFNOSUPPORT The specified address family is not supported. WSAEINPROGRESS A blocking WinSock 1.1 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 The parameter g specified is not valid, or the WSAPROTOCOL_INFO structure that lpProtocolInfo points to is incomplete, the contents are invalid or the WSAPROTOCOL_INFO struct has already been used in an earlier duplicate socket operation. WSAEFAULT 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 WSPStartup See Also accept(), bind(), connect(), getsockname(), getsockopt(), setsockopt(), listen(), recv(), recvfrom(), select(), send(), sendto(), shutdown(), ioctlsocket(). Download 1.64 Mb. Share with your friends:
|