setsockopt (Bluetooth)

  • Article

This function sets a socket option.

Note   This function is actually a Winsock function. However, the information that is presented in it is specific to Bluetooth.

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

Parameters

  • s
    [in] Descriptor identifying a socket. Must be a Bluetooth socket.

  • level
    [in] Level at which the option is defined. Must be SOL_RFCOMM.

  • optname
    [in] Socket option for which the value is to be set. The following table shows possible values for this parameter.

  • Value Description
    SO_BTH_AUTHENTICATE On connected socket, triggers authentication. On not connected socket, forces authentication on connection. For incoming connection this means that connection is rejected if authentication cannot be performed.

    The optval and optlen parameters are ignored; however, Winsock implementation on Windows CE requires optlen to be at least 4 and optval to point to at least an integer datum.
    SO_BTH_ENCRYPT On a connected socket, this command turns encryption on or off. On an unconnected socket, this forces encryption to be on or off on connection. For an incoming connection, this means that the connection is rejected if the encryption cannot be turned on.

    optval is a pointer to int encryption_on;   // TRUE or FALSE;
    optlen is sizeof(int)

    On a connected socket, this command will toggle encryption for all sessions sharing the same Baseband connection. You should use it ONLY if you know what you are doing (for example, yours is the only application); otherwise, the link presumed more secure by another application may become unencrypted.

    For unconnected sockets, encryption can only be turned ON. (If the encryption flag is set to FALSE, it does not initiate encryption request; however, if encryption is already on, it stays on).
    SO_BTH_SET_PIN This sets or revokes PIN code to use with a connection or socket.

    optval must be a pointer to initialized BTH_SOCKOPT_SECURITY structure
    optlen must contain sizeof(BTH_SOCKOPT_SECURITY)
    SO_BTH_SET_LINK This sets or revokes link key to use with a connection or peer device.

    optval must be a pointer to initialized BTH_SOCKOPT_SECURITY structure;
    optlen must contain sizeof(BTH_SOCKOPT_SECURITY)
    SO_BTH_SET_MTU This sets default MTU (maximum transmission unit) for connection negotiation. While allowed for connected socket, it has no effect if the negotiation has already completed. Setting it on listening socket will propagate the value for all incoming connections.

    optval is a pointer to int mtu;
    optlen is sizeof(int)
    SO_BTH_SET_MTU_MAX This sets maximum MTU for connection negotiation. While allowed for connected socket, it has no effect if the negotiation has already completed. Setting it on listening socket will propagate the value for all incoming connections.

    optval is a pointer to int max_mtu;
    optlen is sizeof(int)
    SO_BTH_SET_MTU_MIN This sets minimum MTU for connection negotiation. While allowed for connected socket, it has no effect if the negotiation has already completed. Setting it on listening socket will propagate the value for all incoming connections.

    optval is a pointer to int min_mtu;
    optlen is sizeof(int)
    SO_BTH_SET_XON_LIM This sets XON limit. Setting it on listening socket will propagate the value for all incoming connections.

    XON limit is only used for peers that do not support credit-based flow control (mandatory in the Bluetooth Core Specification version 1.1). When amount of incoming data received, but not read by an application for a given connection grows past this limit, a flow control command is sent to the peer requiring suspension of transmission.

    optval is a pointer to int xon;
    optlen is sizeof(int)
    SO_BTH_SET_XOFF_LIM This sets XOFF limit. Setting it on listening socket will propagate the value for all incoming connections.

    XOFF limit is only used for peers that do not support credit-based flow control (mandatory in the Bluetooth Core Specification 1.1). If flow has been suspended because of buffer run-up, when amount of incoming data received, but not read by an application for a given connection falls below this limit, a flow control command is sent to the peer allowing continuation of transmission.

    optval is a pointer to int xoff;
    optlen is sizeof(int)
    SO_BTH_SET_SEND_BUFFER Specifies maximum amount of data that can be buffered inside RFCOMM (this is amount of data before call to send blocks).

    optval is a pointer to int buffer_size;
    optlen is sizeof(int)
    SO_BTH_SET_RECV_BUFFER Specifies maximum amount of data that can be buffered for a connection. This buffer size is used to compute number of credits granted to peer device when credit-based flow control is implemented. This specifies the maximum amount of data that can be buffered.

    If credit-based flow is not implemented, it is possible to create buffer overruns, because, prior to the Bluetooth Core Specification 1.1, the flow control mechanism does not guarantee adherence to buffer limit (the peer might have already sent more data than can be held before receiving the flow off command. Setting relatively lower limits on XON will make this situation less probable.

    optval is a pointer to int buffer_size;
    optlen is sizeof(int)
    SO_BTH_SEND_MSC Sends MSC command. V24 and breaks are as specified in RFCOMM Specification. Only modem signals and breaks can be controlled, RFCOMM reserved fields such as flow control are ignored and should be set to 0.

    optval is a pointer to { int v24; int breaks; }
    optlen is 2*sizeof(int)
    SO_BTH_SEND_RLS Sends RLS command. Argument is as specified in RFCOMM Specification.

    optval is a pointer to int rls;
    optlen is sizeof(int)
    SO_BTH_SET_PAGE_TO Sets the page timeout for the card. The socket does not have to be connected.

    optval is a pointer to unsigned int page timeout;
    optlen is sizeof(unsigned int)
    SO_BTH_SET_SCAN Sets the scan mode for the card. The socket does not have to be connected.

    optval is a pointer to unsigned int scan mode;
    optlen is sizeof(unsigned int)
    SO_BTH_SET_COD Sets the class of the device. The socket does not have to be connected.

    optval is a pointer to unsigned int cod;
    optlen is sizeof(unsigned int)
    SO_BTH_SET_AUTHN_ENABLE Sets the authentication policy of the device.

    optval is a pointer to unsigned int authentication enable;
    optlen is sizeof(unsigned int)
    SO_BTH_SET_READ_REMOTE_NAME Reads the remote name of the device. The socket does not have to be connected.

    optval is a pointer to a BTH_REMOTE_NAME structure;
    optlen is sizeof(BTH_REMOTE_NAME)
    SO_BTH_SET_LINK_POLICY Sets the link policy for an existing baseband connection. The socket must be connected.

    optval is a pointer to unsigned int link policy;
    optlen is sizeof(unsigned int)

  • optval
    [in] Pointer to the buffer in which the value for the requested option is supplied.

  • optlen
    [in] 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.

Remarks

RFCOMM supports only one connection for a particular server channel between two devices. If application A on device X is connected to server P on device Y, application B on device X will not be able to connect to the same server on device Y. However, device Y will be able to accept an incoming connection on the same server channel from a different device, as well as an incoming connection from device X to a different server channel.

Socket options can be configured for accepting sockets, connecting sockets, and connected sockets.

When a socket option is set for an accepting socket, it is inherited by the socket that is automatically created by Winsock on incoming connections.

When a socket option is set on a connected socket, it overruns whatever the defaults were imposed by its parent socket.

Some parameters are used during negotiation, such as default, minimum and maximum MTU sizes. These values can be manipulated on connected sockets, but have no effect.

For more information about the setsockopt function, see setsockopt (Windows Sockets) in the Winsock reference.

Requirements

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

See Also

Bluetooth Functions | BTH_SOCKOPT_SECURITY | BTH_LOCAL_VERSION | BTH_REMOTE_VERSION | Winsock Extensions | Bluetooth

 Last updated on Thursday, April 08, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.