getsockopt (Windows Sockets)

This function retrieves a socket option.

int getsockopt(
  SOCKET s,
  int level,
  int optname,
  char FAR* optval,
  int FAR* optlen
);

Parameters

• s
  [in] Descriptor identifying a socket.
• level
  [in] Level at which the option is defined; the supported levels include SOL_SOCKET and IPPROTO_TCP.
• optname
  [in] Socket option for which the value is to be retrieved.
• optval
  [out] Pointer to the buffer in which the value for the requested option is to be returned.
• optlen
  [in, out] Pointer to the size of the optval buffer.

Return Values

If no error occurs, this function returns zero. If an error occurs, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.

The following table shows the possible error codes.

Remarks

This function retrieves the current value for a socket option associated with a socket of any type, in any state, and stores the result in optval. Options can exist at multiple protocol levels, but they are always present at the uppermost socket level. Options affect socket operations, such as the packet routing and out of band (OOB) data transfer.

The value associated with the selected option is returned in the buffer optval. The integer pointed to by optlen should originally contain the size of this buffer; on return, it will be set to the size of the value returned. For SO_LINGER, this will be the size of a linger structure. For most other options, it will be the size of an integer.

The application is responsible for allocating any memory space pointed to directly or indirectly by any of the parameters it specified.

If the option was never set with setsockopt (Windows Sockets), then getsockopt returns the default value for the option.

The following options are supported for getsockopt. The Type column identifies the type of data addressed by optval.

level =SOL_SOCKET

level = IPPROTO_TCP

level = NSPROTO_IPX

Note   Windows CE .NET does not support Internetwork Packet Exchange (IPX).

BSD options not supported for getsockopt are as follows.

Calling getsockopt with an unsupported option will result in an error code of WSAENOPROTOOPT being returned from WSAGetLastError.

SO_DEBUG

Windows Sockets service providers are encouraged, but not required, to supply output debug information if the SO_DEBUG option is set by an application. The mechanism for generating the debug information and the form it takes are beyond the scope of this document.

SO_ERROR

The SO_ERROR option returns and resets the per socket–based error code, which is different from the per thread based–error code that is handled using the WSAGetLastError and WSASetLastError function calls. A successful call using the socket does not reset the socket-based error code returned by the SO_ERROR option.

SO_GROUP_ID

This option is reserved. This option is also exclusive to getsockopt and the value should be NULL.

SO_GROUP_PRIORITY

This option is reserved.

SO_KEEPALIVE

An application can request that a TCP/IP service provider enable the use of keep-alive packets on TCP connections by turning on the SO_KEEPALIVE socket option. A Windows Sockets provider need not support the use of keep-alive. If it does, the precise semantics are implementation-specific but should conform to section 4.2.3.6 of RFC 1122: Requirements for Internet Hosts — Communication Layers. If a connection is dropped as the result of keep-alives, the error code WSAENETRESET is returned to any calls in progress on the socket and any subsequent calls will fail with WSAENOTCONN. SO_KEEPALIVE is not supported on ATM sockets, and requests to enable the use of keep-alive packets on an ATM socket results in an error being returned by the socket.

SO_LINGER

SO_LINGER controls the action taken when unsent data is queued on a socket and a closesocket is performed. See closesocket for a description of the way in which the SO_LINGER settings affect the semantics of closesocket. The application gets the current behavior by retrieving a linger structure (pointed to by the optval parameter).

SO_MAX_MSG_SIZE

This is a get-only socket option that indicates the maximum outbound (send) size of a message for message-oriented socket types (for example, SOCK_DGRAM) as implemented by a particular service provider. It has no description for byte stream oriented sockets. There is no provision to find out the maximum inbound–message size.

SO_PROTOCOL_INFO

This is a get-only option that supplies the WSAPROTOCOL_INFO structure associated with this socket. See WSAEnumProtocols for more information about this structure.

SO_SNDBUF

When a Windows Sockets implementation supports the SO_RCVBUF and SO_SNDBUF options, an application can request different buffer sizes (larger or smaller). The call to setsockopt can succeed even if the implementation did not provide the whole amount requested. An application must call this function with the same option to check the buffer size actually provided.

SO_REUSEADDR

By default, a socket cannot be bound (see bind (Windows Sockets)) to a local address that is already in use. On occasion, however, it can be necessary to reuse an address in this way. Because every connection is uniquely identified by the combination of local and remote addresses, there is no problem with having two sockets bound to the same local address as long as the remote addresses are different. To inform the Windows Sockets provider that a bind on a socket should not be disallowed because the desired address is already in use by another socket, the application should set the SO_REUSEADDR socket option for the socket before issuing the bind. Note that the option is interpreted only at the time of the bind. It is therefore unnecessary (but harmless) to set the option on a socket that is not to be bound to an existing address and setting or resetting the option after the bind has no effect on this or any other socket. SO_REUSEADDR is not applicable for ATM sockets, and although requests to reuse and address do not result in an error, they have no affect on when an ATM socket is in use.

PVD_CONFIG

This option retrieves an opaque data structure object from the service provider associated with socket s. This object stores the current configuration information of the service provider. The exact format of this data structure is service provider specific.

TCP_NODELAY

The TCP_NODELAY option is specific to TCP/IP service providers. The Nagle algorithm is disabled if the TCP_NODELAY option is enabled (and vice versa). The Nagle algorithm (described in RFC 896) is very effective in reducing the number of small packets sent by a host. The process involves buffering send data when there is unacknowledged data already in flight or buffering send data until a full-size packet can be sent. It is highly recommended that Windows Sockets implementations enable the Nagle Algorithm by default because, for the vast majority of application protocols, the Nagle Algorithm can deliver significant performance enhancements. However, for some applications this algorithm can impede performance, and setsockopt with the same option can be used to turn it off. These are applications where many small messages are sent, and the time delays between the messages are maintained.

Notes for IrDA Sockets

• The Af_irda.h header file must be explicitly included.
• Windows NT® and Windows 2000 will return WSAENETDOWN to indicate the underlying transceiver driver failed to initialize with the IrDA protocol stack.
• IrDA supports special socket options. The following table shows these options.

  Value	Type	Description
  IRLMP_ENUMDEVICES	*DEVICELIST	Describes devices in range.
  IRLMP_IAS_QUERY	*IAS_QUERY	Retrieve Information Access Service (IAS) attributes.

Before an IrDA socket connection can be initiated, a device address must be obtained by performing a getsockopt(IRLMP_ENUMDEVICES) function call, which returns a list of all available IrDA devices. A device address returned from the function call is copied into a SOCKADDR_IRDA structure, which in turn is used by a subsequent call to the connect function call.

Discovery can be performed in two ways. First, performing a getsockopt function call with the IRLMP_ENUMDEVICES option causes a single discovery to be run on each idle adapter. The list of discovered devices and cached devices (on active adapters) is returned immediately. The following code example demonstrates this approach.

SOCKADDR_IRDA     DestSockAddr = { AF_IRDA, 0, 0, 0, 0, "SampleIrDAService" };
#define DEVICE_LIST_LEN    10
unsigned char    DevListBuff[sizeof(DEVICELIST) –
                 sizeof(IRDA_DEVICE_INFO) +
                 (sizeof(IRDA_DEVICE_INFO) * DEVICE_LIST_LEN)];
int              DevListLen    = sizeof(DevListBuff);
PDEVICELIST      pDevList      = (PDEVICELIST) &DevListBuff;
pDevList->numDevice = 0;
// Sock is not in connected state
if (getsockopt(Sock, SOL_IRLMP, IRLMP_ENUMDEVICES,
               (char *) pDevList, &DevListLen) == SOCKET_ERROR)
{
        // WSAGetLastError 
}
if (pDevList->numDevice == 0)
{
        // no devices discovered or cached
        // not a bad idea to run a couple of times
}
else
{
       // one per discovered device
       for (i = 0; i < (int) pDevList->numDevice; i++)
       {
            // typedef struct _IRDA_DEVICE_INFO
            // {
            //     u_char    irdaDeviceID[4];
            //     char      irdaDeviceName[22];
            //     u_char    irdaDeviceHints1;
            //     u_char    irdaDeviceHints2;
            //     u_char    irdaCharSet;
            // } _IRDA_DEVICE_INFO;
            // pDevList->Device[i]. see _IRDA_DEVICE_INFO for fields
            // display the device names and let the user select one
       }
}
// assume the user selected the first device [0]
memcpy(&DestSockAddr.irdaDeviceID[0], &pDevList->Device[0].irdaDeviceID[0], 4);
if (connect(Sock, (const struct sockaddr *) &DestSockAddr,
            sizeof(SOCKADDR_IRDA)) == SOCKET_ERROR)
{
       // WSAGetLastError
}

The second approach to performing discovery of IrDA device addresses is to perform a lazy discovery. In this approach, the application is not notified until the discovered devices list changes from the last discovery run by the stack.

The IAS_QUERY structure shown in the Type column in the previous table is used to retrieve a single attribute of a single class from a peer device's IAS database. The application specifies the device and class to query and the attribute and attribute type. Note that the device would have been obtained previously by a call to getsockopt(IRLMP_ENUMDEVICES). It is expected that the application allocates a buffer, of the necessary size, for the returned parameters.

Many SO level socket options are not meaningful to IrDA; only SO_LINGER and SO_DONTLINGER are specifically supported.

Requirements

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

See Also

bind (Windows Sockets) | closesocket | setsockopt (Windows Sockets) | socket (Windows Sockets) | WSAConnect | WSAEnumProtocols | WSAGetLastError | WSASetLastError | WSAStartup | linger | SOCKADDR_IRDA

 Last updated on Saturday, April 10, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.