Function and syntax of commands

A. WSAStartup
B. WSALookupServiceBegin
C. WSALookupServiceNext
D. WSAAddressToString
E. select
F. connect
G. bind
H. send

Requirements
Header
Winsock2.h
Library
Ws2_32.lib
DLL
Ws2_32.dll








WSAStartup function
The WSAStartup function initiates use of the Winsock DLL by a process.
Syntax
C++

int WSAStartup(
_In_ WORD wVersionRequested,
_Out_ LPWSADATA lpWSAData
);

Parameters
wVersionRequested [in]
The highest version of Windows Sockets specification that the caller can use. The high-
order byte specifies the minor version number; the low-order byte specifies the major
version number.
lpWSAData [out]
A pointer to the WSADATA data structure that is to receive details of the Windows
Sockets implementation.
Return value
If successful, the WSAStartup function returns zero. Otherwise, it returns one of the error codes
listed below.
The WSAStartup function directly returns the extended error code in the return value for this
function. A call to the WSAGetLastError function is not needed and should not be used.

Bluetooth and WSALookupServiceBegin
Bluetooth uses the WSALookupServiceBegin function to query for devices and to discover services
Flag Result
LUP_CONTAINERS
Specifies that the query
purpose is to obtain a list of
Bluetooth devices and not a
list of services. This flag
must be set.
LUP_FLUSHCACHE
Triggers an inquiry of local
devices or causes cached
results from previous queries
to be returned.
LUP_RETURN_TYPE
Return the Bluetooth COD
(class of device bits) directly
in the lpServiceClassId
member of the
WSAQUERYSET structure.
The COD is mapped to the
Data1 member of the GUID.
LUP_RES_SERVICE
Return information for the
local Bluetooth address. This
flag has an effect only if
LUP_RETURN_ADDR is
also specified.
LUP_RETURN_NAME
Return the display name of
the device in the
lpszServiceInstanceName
member of the
WSAQUERYSET structure
for each call to the
WSALookupServiceNext
function. This flag must also
be specified to retrieve the
name member of the
BTH_DEVICE_INFO
structure when specifying the
LUP_RETURN_BLOB
flag.
LUP_RETURN_ADDR
Return a
SOCKADDR_BTH
structure that contains the
48-bit address of the peer in
the lpcsaBuffer member of
the WSAQUERYSET
structure for each call to the
WSALookupServiceNext
function. Other members in
the SOCKADDR_BTH
structure will be empty.
LUP_RETURN_BLOB
Return the
BTH_DEVICE_INFO
structure on each subsequent
call to
WSALookupServiceNext.
LUP_FLUSHPREVIOUS
Skip the next available
device, and return the device
that follows it.

WSALookupServiceNext function
The WSALookupServiceNext function is called after obtaining a
handle from a previous call to WSALookupServiceBegin in order
to retrieve the requested service information.
The provider will pass back a WSAQUERYSET structure in the
lpqsResults buffer. The client should continue to call this function
until it returns WSA_E_NO_MORE, indicating that all of
WSAQUERYSET has been returned.
Syntax
C++

INT WSALookupServiceNext(
_In_ HANDLE hLookup,
_In_ DWORD dwControlFlags,
_Inout_ LPDWORD lpdwBufferLength,
_Out_ LPWSAQUERYSET lpqsResults
);

Parameters
hLookup [in]
A handle returned from the previous call to
WSALookupServiceBegin.
dwControlFlags [in]
A set of flags that controls the operation. The values passed
in the dwControlFlags parameter to the
WSALookupServiceBegin function determine the
possible criteria. Any values passed in the dwControlFlags
parameter to the WSALookupServiceNext function
further restrict the criteria for the service lookup.

Currently, LUP_FLUSHPREVIOUS is defined as a means
to cope with a result set that is too large. If an application
does not (or cannot) supply a large enough buffer, setting
LUP_FLUSHPREVIOUS instructs the provider to discard
the last result setwhich was too largeand move on to
the next set for this call.
Supported values for the dwControlFlags parameter are
defined in the Winsock2.h header file and can be a
combination of the following options.
Flag Meaning
LUP_DEEP
0x0001
Queries deep as opposed to
just the first level.
LUP_CONTAINERS
0x0002
Returns containers only.
LUP_NOCONTAINERS
0x0004
Do not return containers.
LUP_NEAREST
0x0008
If possible, returns results in
the order of distance. The
measure of distance is
provider specific.
LUP_RETURN_NAME
0x0010
Retrieves the name as
lpszServiceInstanceName.
LUP_RETURN_TYPE
0x0020
Retrieves the type as
lpServiceClassId.
LUP_RETURN_VERSION
0x0040
Retrieves the version as
lpVersion.
LUP_RETURN_COMMENT
0x0080
Retrieves the comment as
lpszComment.
LUP_RETURN_ADDR
0x0100
Retrieves the addresses as
lpcsaBuffer.
LUP_RETURN_BLOB
0x0200
Retrieves the private data as
lpBlob.
LUP_RETURN_ALIASES
0x0400
Any available alias
information is to be returned
in successive calls to
WSALookupServiceNext,
and each alias returned will
have the
RESULT_IS_ALIAS flag
set.
LUP_RETURN_QUERY_STRING
0x0800
Retrieves the query string
used for the request.
LUP_RETURN_ALL
0x0FF0
A set of flags that retrieves
all of the LUP_RETURN_*
values.
LUP_FLUSHPREVIOUS
0x1000
Used as a value for the
dwControlFlags parameter
in
WSALookupServiceNext.
Setting this flag instructs the
provider to discard the last
result set, which was too
large for the specified buffer,
and move on to the next
result set.
LUP_FLUSHCACHE
0x2000
If the provider has been
caching information, ignores
the cache, and queries the
namespace itself.
LUP_RES_SERVICE
0x8000
This indicates whether prime
response is in the remote or
local part of
CSADDR_INFO structure.
The other part needs to be
usable in either case.

lpdwBufferLength [in, out]
On input, the number of bytes contained in the buffer
pointed to by lpqsResults. On output, if the function fails
and the error is WSAEFAULT, then it contains the
minimum number of bytes to pass for the lpqsResults to
retrieve the record.
lpqsResults [out]
A pointer to a block of memory, which will contain one
result set in a WSAQUERYSET structure on return.
Return value
The return value is zero if the operation was successful.
Otherwise, the value SOCKET_ERROR is returned, and a specific
error number can be retrieved by calling WSAGetLastError.
WSAAddressToString function
The WSAAddressToString function converts all components of a
sockaddr structure into a human-readable string representation of
the address.
This is intended to be used mainly for display purposes. If the
caller requires that the translation to be performed by a particular
provider, it should supply the corresponding
WSAPROTOCOL_INFO structure in the lpProtocolInfo
parameter.
Syntax
C++

INT WSAAPI WSAAddressToString(
_In_ LPSOCKADDR lpsaAddress,
_In_ DWORD dwAddressLength,
_In_opt_ LPWSAPROTOCOL_INFO lpProtocolInfo,
_Inout_ LPTSTR lpszAddressString,
_Inout_ LPDWORD lpdwAddressStringLength
);

Parameters
lpsaAddress [in]
A pointer to the sockaddr structure to translate into a
string.
dwAddressLength [in]
The length, in bytes, of the address in the sockaddr
structure pointed to by the lpsaAddress parameter. The
dwAddressLength parameter may vary in size with
different protocols.
lpProtocolInfo [in, optional]
A pointer to the WSAPROTOCOL_INFO structure for a
particular provider. If this is parameter is NULL, the call is
routed to the provider of the first protocol supporting the
address family indicated in the lpsaAddress parameter.
lpszAddressString [in, out]
A pointer to the buffer that receives the human-readable
address string.
lpdwAddressStringLength [in, out]
On input, this parameter specifies the length of the buffer
pointed to by the lpszAddressString parameter. The length
is represented in bytes for ANSI strings, and in WCHARs
for Unicode strings. On output, this parameter returns the
length of the string including the NULL terminator
actually copied into the buffer pointed to by the
lpszAddressString parameter. If the specified buffer is not
large enough, the function fails with a specific error of
WSAEFAULT and this parameter is updated with the
required size.
Return value
If no error occurs, WSAAddressToString returns a value of zero.
Otherwise, the value SOCKET_ERROR is returned, and a specific
error number can be retrieved by calling WSAGetLastError.
send function
The send function sends data on a connected socket.
Syntax
C++

int send(
_In_ SOCKET s,
_In_ const char *buf,
_In_ int len,
_In_ int flags
);

Parameters
s [in]
A descriptor identifying a connected socket.
buf [in]
A pointer to a buffer containing the data to be transmitted.
len [in]
The length, in bytes, of the data in buffer pointed to by the
buf parameter.
flags [in]
A set of flags that specify the way in which the call is
made. This parameter is constructed by using the bitwise
OR operator with any of the following values.
Value Meaning
MSG_DONTROUTE
Specifies that the data should not be
subject to routing. A Windows Sockets
service provider can choose to ignore
this flag.
MSG_OOB Sends OOB data (stream-style socket
such as SOCK_STREAM only.

Return value
If no error occurs, send returns the total number of bytes sent,
which can be less than the number requested to be sent in the len
parameter. Otherwise, a value of SOCKET_ERROR is returned,
and a specific error code can be retrieved by calling
WSAGetLastError.
select function
The select function determines the status of one or more sockets,
waiting if necessary, to perform synchronous I/O.
Syntax
C++

int select(
_In_ int nfds,
_Inout_ fd_set *readfds,
_Inout_ fd_set *writefds,
_Inout_ fd_set *exceptfds,
_In_ const struct timeval *timeout
);

Parameters
nfds [in]
Ignored. The nfds parameter is included only for
compatibility with Berkeley sockets.
readfds [in, out]
An optional pointer to a set of sockets to be checked for
readability.
writefds [in, out]
An optional pointer to a set of sockets to be checked for
writability.
exceptfds [in, out]
An optional pointer to a set of sockets to be checked for
errors.
timeout [in]
The maximum time for select to wait, provided in the form
of a TIMEVAL structure. Set the timeout parameter to
null for blocking operations.
Return value
The select function returns the total number of socket handles that
are ready and contained in the fd_set structures, zero if the time
limit expired, or SOCKET_ERROR if an error occurred. If the
return value is SOCKET_ERROR, WSAGetLastError can be
used to retrieve a specific error code.
Requirements
Header
Winsock2.h
Library
Ws2_32.lib
DLL
Ws2_32.dll

connect function
The connect function establishes a connection to a specified
socket.
Syntax
C++

int connect(
_In_ SOCKET s,
_In_ const struct sockaddr *name,
_In_ int namelen
);

Parameters
s [in]
A descriptor identifying an unconnected socket.
name [in]
A pointer to the sockaddr structure to which the
connection should be established.
namelen [in]
The length, in bytes, of the sockaddr structure pointed to
by the name parameter.
Return value
If no error occurs, connect returns zero. Otherwise, it returns
SOCKET_ERROR, and a specific error code can be retrieved by
calling WSAGetLastError.

Requirements
Header
Winsock2.h
Library
Ws2_32.lib
DLL
Ws2_32.dll
bind function
The bind function associates a local address with a socket.
Syntax
C++

int bind(
_In_ SOCKET s,
_In_ const struct sockaddr *name,
_In_ int namelen
);

Parameters
s [in]
A descriptor identifying an unbound socket.
name [in]
A pointer to a sockaddr structure of the local address to assign to the bound socket .
namelen [in]
The length, in bytes, of the value pointed to by the name parameter.
Return value
If no error occurs, bind returns zero. Otherwise, it returns SOCKET_ERROR, and a specific
error code can be retrieved by calling WSAGetLastError.