Share via

HCI_EstablishDeviceContext (Compact 2013)

  • Article

3/26/2014

This function establishes a connection between the host and the controller.

Syntax

Int HCI_EstablishDeviceContext(
  Void *pUserContext,
  UINT uiControl,
  BD_ADDR *pba,
  UINT class_of_device,
  UCHAR link_type,
  HCI_EVENT_INDICATION *pInd,
  HCI_CALLBACKS *pCall,
  HCI_INTERFACE *pInt,
    Int *pcDataHeaders,
    Int *pcDataTrailers,
  HANDLE *phDeviceContext
);

Parameters

  • pUserContext
    [in] Pointer to the user context information. It is used in asynchronous event indications.

  • uiControl
    [in] Filter and routing options. One of the following values:

    • BTH_CONTROL_ROUTE_ALL (reserved)
    • BTH_CONTROL_DEVICEONLY

    Specify routing by combining one or more of the following values with the previous value:

    • BTH_CONTROL_ROUTE_BY_ADDR
    • BTH_CONTROL_ROUTE_BY_COD
    • BTH_CONTROL_ROUTE_BY_LINKTYPE
    • BTH_CONTROL_ROUTE_HARDWARE
    • BTH_CONTROL_ROUTE_SECURITY

    See the remarks below for details on using these options.

  • pba
    [in] Pointer to the remote device address. Required if you specify BTH_CONTROL_ROUTE_BY_ADDR.
  • class_of_device
    [in] Class of Device. Required if you specify BTH_CONTROL_ROUTE_BY_COD.
  • link_type
    [in] Link type. Required if you specify BTH_CONTROL_ROUTE_BY_LINKTYPE.
  • pInd
    [in] Points to the Host Controller Interface (HCI) event handlers.
  • pCall
    [in] Points to the HCI callbacks.
  • pInt
    [out] Points to HCI command functions.
  • pcDataHeaders
    [out] Points to the size of data headers in the HCI data packets.
  • pcDataTrailers
    [out] Points to the size of data trailers in the HCI data packets.
  • phDeviceContext
    [out] Points to the device context handle.

Return Value

The following table shows the possible return values.

Value

Description

ERROR_SUCCESS

Success.

ERROR_INVALID_PARAMETER

One of the parameters is not valid.

ERROR_OUTOFMEMORY

Unable to create the device context.

ERROR_SERVICE_NOT_ACTIVE

The Bluetooth stack is not present.

ERROR_SHARING_VIOLATION

The specified parameters conflict with the default L2CAP layer.

Remarks

A stack layer specifies BTH_CONTROL_ROUTE_BY_ADDR and a pointer to pba to only accept connections from one device. To accept only SCO connections, it specifies the appropriate link_type and BTH_CONTROL_ROUTE_BY_LINKTYPE. The same hold true for class of device.

BTH_CONTROL_ROUTE_SECURITY is specifically implemented to support security manager layers. If a layer installs itself with this flag, the link key/pin requests for all connections are forwarded to it.

BTH_CONTROL_ROUTE_ALL is reserved for the default handler. Only one stack layer can be a default handler. In the Bluetooth stack this role is handled by L2CAP.

BTH_CONTROL_ROUTE_DEVICEONLY is specifically reserved for management layers that do not accept incoming connections at all. There may be more than one of these.

Output parameters pcDataHeaders and pcDataTrailers define how many bytes must be reserved in the data packet by upper layers for HCI level protocol headers and trailers. Incoming data packets must have BD_BUFFER::cStart equal to *pcDataHeaders, and BD_BUFFER::cEnd to be equal to BD_BUFFER::cSize minus * pcDataTrailers.

Requirements

Header

bt_hcip.h

Library

Btd.lib

See Also

Reference

Bluetooth HCI Functions
HCI_EVENT_INDICATION
HCI_CALLBACKS
HCI_INTERFACE
BD_BUFFER