Partager via

setsockopt (Bluetooth) (Compact 2013)

  • Article

3/26/2014

This function sets a socket option.

Syntax

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 a connected socket, triggers authentication. On an unconnected socket, forces authentication on connection. For incoming connection this means that connection is rejected if authentication cannot be performed.

    Theoptval and optlen parameters are ignored; however, Winsock implementation on Windows Embedded Compact requires optlen to be at least 4 and optval to point to at least an integer variable.

    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 upon connection. For an incoming connection, this means that the connection is rejected if the encryption cannot be turned on.

    optval is a pointer to an encryption-enabled flag of int type. The flag should be TRUE to enable encryption or FALSE to disable encryption. 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 Maximum Transmission Unit (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 an MTU value of type unsignedint; optlen is sizeof(unsigned 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 a maximum MTU value of type unsignedint; optlen is sizeof(unsigned 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 a minimum MTU value of type unsignedint; optlen is sizeof(unsigned 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 an XON limit value of type unsignedint; optlen is sizeof(unsigned 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 an XOFF limit value of type unsignedint; optlen is sizeof(unsigned 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 sendblocks).

    optval is a pointer to a buffer size of type unsignedint; optlen is sizeof(unsigned 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 a buffer size of type unsignedint; optlen is sizeof(unsigned int).

    SO_BTH_SEND_MSC

    Sends MSC command. V24 and breaks are as specified in the 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. The socket must be connected.

    optval is a pointer to a structure defined as follows:

    struct {
  int v24;
  int breaks;
}

    optlen is 2*sizeof(int).

    SO_BTH_SEND_RLS

    Sends RLS command. Argument is as specified in the RFCOMM Specification.

    optval is a pointer to the RLS argument of type unsignedint; optlen is sizeof(unsigned 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 the page timeout value of type unsigned int; 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 the scan mode value of type unsigned int; 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 the class of device value of type unsigned int; optlen is sizeof(unsigned int).

    SO_BTH_SET_AUTHN_ENABLE

    Sets the authentication policy of the device.

    optval is a pointer to the authentication enabled value of type unsigned int; optlen is sizeof(unsigned int).

    SO_BTH_SET_SECURITY_LEVEL

    Sets the Secure Simple Pairing security level of the connection. The device does not have to be connected.

    optval is a pointer to a security level value of type BTSecurityLevel; optlen is sizeof(BTSecurityLevel).

    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 the link policy value of type unsigned int; optlen is sizeof(unsigned int).

    SO_BTH_ENTER_HOLD_MODE

    Places the ACL connection to the specified peer device in HOLD mode. The device must be connected.

    optval is a pointer to the BTH_HOLD_MODE structure; optlen is sizeof(BTH_HOLD_MODE).

    SO_BTH_ENTER_SNIFF_MODE

    Places the ACL connection to the specified peer device in SNIFF mode. The device must be connected.

    optval is a pointer to the BTH_SNIFF_MODE structure; optlen is sizeof(BTH_SNIFF_MODE).

    SO_BTH_EXIT_SNIFF_MODE

    Forces the ACL connection to the peer device to leave SNIFF mode. The device must be connected.

    SO_BTH_ENTER_PARK_MODE

    Places the ACL connection to the peer device in PARK mode. The device must be connected.

    optval is a pointer to the BTH_PARK_MODE structure; optlen is sizeof(BTH_PARK_MODE).

    SO_BTH_EXIT_PARK_MODE

    Forces the ACL connection to the peer device to leave PARK mode. The device must be connected.

    SO_BTH_GET_MODE

    Retrieves the current role for peer Bluetooth device.
  • optval
    [in] Pointer to the buffer in which the value for the requested option is supplied.
  • optlen
    [in] Size of the optvalbuffer.

Return Value

Returns zero on success; otherwise SOCKET_ERROR. The specific error code can be retrieved by calling WSAGetLastError.

Remarks

Note

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

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

Header

winsock2.h,
ws2bth.h

Library

Ws2.lib

See Also

Reference

Bluetooth API Miscellaneous Functions
BTH_SOCKOPT_SECURITY
BTH_LOCAL_VERSION
BTH_REMOTE_VERSION