Partager via

getsockopt (Bluetooth) (Compact 2013)

  • Article

3/26/2014

This function retrieves a socket option.

Syntax

int getsockopt(
  SOCKET s,
  int level,
  int optname,
  char FAR* optval,
  int FAR* 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 retrieved. The following table shows possible values for this parameter:

    Value

    Description

    SO_BTH_GET_MTU

    Returns Maximum Transmission Unit (MTU). For a connected socket, this is negotiated value, for a server (accepting) socket it is MTU proposed for negotiation on connection request.

    optval is a pointer to an unsigned int variable; it will be populated with the MTU. optlen is sizeof(unsigned int).

    SO_BTH_GET_MTU_MAX

    Returns maximum acceptable MTU value for a connection on this socket. Because negotiation has already happened, has little meaning for connected socket.

    optval is a pointer to an unsigned int variable; it will be populated with the maximum MTU value. optlen is sizeof(unsigned int).

    SO_BTH_GET_MTU_MIN

    Returns minimum acceptable MTU value for a connection on this socket. Because negotiation has already happened, has little meaning for connected socket.

    optval is a pointer to an unsigned int variable; it will be populated with the minimum MTU value. optlen is sizeof(unsigned int).

    SO_BTH_GET_XON_LIM

    Returns XON limit for a connection. 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 unsigned int variable; it will be populated with the XON limit. optlen is sizeof(unsigned int).

    SO_BTH_GET_XOFF_LIM

    Returns XOFF limit for a connection. 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 unsigned int variable; it will be populated with the XOFF limit. optlen is sizeof(unsigned int).

    SO_BTH_GET_RECV_BUFFER

    Returns 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 an unsigned int variable; it will be populated with the receive buffer size. optlen is sizeof(unsigned int).

    SO_BTH_GET_SEND_BUFFER

    Returns maximum amount of data that can be buffered inside RFCOMM (this is the amount of data before a call to send blocks).

    optval is a pointer to an unsigned int variable; it will be populated with the send buffer size. optlen is sizeof(unsigned int).

    SO_BTH_GET_V24_BR

    Retrieves last v24 and break signals set through MSC command from peer device. The socket must be connected.

    optval is a pointer to the following structure:

    struct {
  int v24;
  int breaks;
}

    optlen is 2*sizeof(int).

    This call never blocks, even if no status update is received. It will always return the last (or default) values.

    SO_BTH_GET_RLS

    Retrieves last line status (RLS) signals set through RLS command from peer device. The socket must be connected.

    optval is a pointer to an int variable; it will be populated with the RLS value. optlen is sizeof(int).

    This call never blocks, even if no status update is received. It will always return the last (or default) values.

    SO_BTH_GET_FLOW_TYPE

    Gets flow control type on the connected socket.

    optval is a pointer to an unsigned int variable; the variable will be set to zero (0) for legacy flow control or one (1) for credit-based flow control. optlen is sizeof(unsigned int).

    SO_BTH_GET_PAGE_TO

    Gets the current page timeout. The socket does not have to be connected.

    optval is a pointer to an unsigned int variable; it will be populated with the current page timeout value. optlen is sizeof(unsigned int).

    SO_BTH_GET_SCAN

    Gets the current scan mode. The socket does not have to be connected.

    optval is a pointer to an unsigned int variable; it will be populated with the current scan mode. optlen is sizeof(unsigned int).

    SO_BTH_GET_COD

    Gets the current class of the device. The socket does not have to be connected.

    optval is a pointer to an unsigned int variable; it will be populated with the class of device value. optlen is sizeof(unsigned int).

    SO_BTH_GET_LOCAL_VER

    Gets the local version of the baseband and L2CAP. The socket does not have to be connected.

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

    SO_BTH_GET_REMOTE_VER

    Gets the Host Controller Interface (HCI) version of the peer device.

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

    SO_BTH_GET_AUTHN_ENABLE

    Retrieves the authentication enabled setting. The socket does not have to be connected.

    optval is a pointer to an unsigned int variable; it will be populated with the authentication enabled setting. optlen is sizeof(unsigned int).

    SO_BTH_GET_SECURITY_LEVEL

    Retrieves the Bluetooth connection security level. The socket does not have to be connected.

    optval is a pointer to a BTSecurityLevel variable; it will be populated with the security level. optlen is sizeof(BTSecurityLevel).

    SO_BTH_GET_LINK_POLICY

    Retrieves the link policy of the device. The socket must be connected.

    optval is a pointer to an int variable; it will be populated with the link policy value. optlen is sizeof(int).

    SO_BTH_GET_MODE

    Gets the current mode of the connection. The mode can either be sniff, park, or hold. The socket must be connected.

    optval is a pointer to an int variable; it will be populated with the current connection mode value. optlen is sizeof(int).
  • 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 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.

For more information about the getsockopt function, see getsockopt (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