# Bluetooth® SDP API

## Overview

SDP (Service Discovery Protocol) API enables devices to discover services and service attributes offered by remote Bluetooth devices. It supports service search, service attribute retrieval, and the establishment of service connections.

## Application Examples

- bluetooth/bluedroid/classic_bt/bt_l2cap_client demonstrates how to use SDP APIs to search for services on remote Bluetooth devices. It shows how to register SDP callbacks, initialize SDP, perform service discovery using `esp_sdp_search_record()`, and retrieve the L2CAP PSM (Protocol/Service Multiplexer) value from the search results to establish an L2CAP connection.

- bluetooth/bluedroid/classic_bt/bt_l2cap_server demonstrates how to use SDP APIs to create and publish service records. It shows how to register SDP callbacks, initialize SDP, create an SDP record using `esp_sdp_create_record()` with L2CAP PSM information, making the service discoverable by remote clients.

## API Reference

### Header File

- components/bt/host/bluedroid/api/include/api/esp_sdp_api.h

- This header file can be included with:

  >     #include "esp_sdp_api.h"

- This header file is a part of the API provided by the `bt` component. To declare that your component depends on `bt`, add the following to your CMakeLists.txt:

  >     REQUIRES bt

  > or

  >     PRIV_REQUIRES bt

### Functions

esp_err_t esp_sdp_register_callback(esp_sdp_cb_t callback)

  This function is called to init callbacks with SDP module.

  Parameters:

    callback -- [in] pointer to the init callback function.

  Returns:

    - ESP_OK: success

    - other: failed

esp_err_t esp_sdp_init(void)

  This function is called to init SDP module. When the operation is completed, the callback function will be called with ESP_SDP_INIT_EVT. This function should be called after esp_bluedroid_enable() completes successfully.

  Returns:

    - ESP_OK: success

    - other: failed

esp_err_t esp_sdp_deinit(void)

  This function is called to de-initialize SDP module. The operation will remove all SDP records, then the callback function will be called with ESP_SDP_REMOVE_RECORD_COMP_EVT, and the number of ESP_SDP_REMOVE_RECORD_COMP_EVT is equal to the number of SDP records.When the operation is completed, the callback function will be called with ESP_SDP_DEINIT_EVT. This function should be called after esp_sdp_init() completes successfully.

  Returns:

    - ESP_OK: success

    - other: failed

esp_err_t esp_sdp_search_record(esp_bd_addr_t bd_addr, esp_bt_uuid_t uuid)

  Perform service discovery for the services provided by the given peer device. When the operation is completed, the callback function will be called with ESP_SDP_SEARCH_COMP_EVT. This function must be called after esp_sdp_init() successful and before esp_sdp_deinit().

  Parameters:

    - bd_addr -- [in] Remote device bluetooth device address.

    - uuid -- [in] Service UUID of the remote device.

  Returns:

    - ESP_OK: success

    - other: failed

esp_err_t esp_sdp_create_record(esp_bluetooth_sdp_record_t *record)

  This function is called to create SDP records. When the operation is completed, the callback function will be called with ESP_SDP_CREATE_RECORD_COMP_EVT. This function must be called after esp_sdp_init() successful and before esp_sdp_deinit().

  Parameters:

    record -- [in] The SDP record to create.

  Returns:

    - ESP_OK: success

    - other: failed

esp_err_t esp_sdp_remove_record(int record_handle)

  Remove an SDP record. When the operation is completed, the callback function will be called with ESP_SDP_REMOVE_RECORD_COMP_EVT. This function must be called after esp_sdp_init() successful and before esp_sdp_deinit().

  Parameters:

    record_handle -- [in] The SDP record handle.

  Returns:

    - ESP_OK: success

    - other: failed

esp_err_t esp_sdp_get_protocol_status(esp_sdp_protocol_status_t *status)

  This function is used to get the status of SDP.

  Parameters:

    status -- [out] - sdp status

  Returns:

    - ESP_OK: success

    - other: failed

### Unions

union esp_bluetooth_sdp_record_t
  #include <esp_sdp_api.h>

  SDP record parameters union.

  Public Members

  esp_bluetooth_sdp_hdr_overlay_t hdr

    General info

  esp_bluetooth_sdp_raw_record_t raw

    Raw SDP search data for unknown UUIDs

  esp_bluetooth_sdp_mas_record_t mas

    Message Access Profile - Server

  esp_bluetooth_sdp_mns_record_t mns

    Message Access Profile - Client (Notification Server)

  esp_bluetooth_sdp_pse_record_t pse

    Phone Book Profile - Server

  esp_bluetooth_sdp_pce_record_t pce

    Phone Book Profile - Client

  esp_bluetooth_sdp_ops_record_t ops

    Object Push Profile

  esp_bluetooth_sdp_sap_record_t sap

    SIM Access Profile

  esp_bluetooth_sdp_dip_record_t dip

    Device Identification Profile

union esp_sdp_cb_param_t
  #include <esp_sdp_api.h>

  SDP callback parameters union.

  Public Members

  struct esp_sdp_cb_param_t::sdp_init_evt_param init

    SDP callback param of ESP_SDP_INIT_EVT

  struct esp_sdp_cb_param_t::sdp_deinit_evt_param deinit

    SDP callback param of ESP_SDP_DEINIT_EVT

  struct esp_sdp_cb_param_t::sdp_search_evt_param search

    SDP callback param of ESP_SDP_SEARCH_COMP_EVT

  struct esp_sdp_cb_param_t::sdp_create_record_evt_param create_record

    SDP callback param of ESP_SDP_CREATE_RECORD_COMP_EVT

  struct esp_sdp_cb_param_t::sdp_remove_record_evt_param remove_record

    SDP callback param of ESP_SDP_REMOVE_RECORD_COMP_EVT

  struct sdp_create_record_evt_param
    #include <esp_sdp_api.h>

    ESP_SDP_CREATE_RECORD_COMP_EVT.

    Public Members

    esp_sdp_status_t status

      Status

    int record_handle

      SDP record handle

  struct sdp_deinit_evt_param
    #include <esp_sdp_api.h>

    ESP_SDP_DEINIT_EVT.

    Public Members

    esp_sdp_status_t status

      Status

  struct sdp_init_evt_param
    #include <esp_sdp_api.h>

    ESP_SDP_INIT_EVT.

    Public Members

    esp_sdp_status_t status

      Status

  struct sdp_remove_record_evt_param
    #include <esp_sdp_api.h>

    ESP_SDP_REMOVE_RECORD_COMP_EVT.

    Public Members

    esp_sdp_status_t status

      Status

    int record_handle

      SDP record handle

  struct sdp_search_evt_param
    #include <esp_sdp_api.h>

    ESP_SDP_SEARCH_COMP_EVT.

    Public Members

    esp_sdp_status_t status

      Status

    esp_bd_addr_t remote_addr

      Remote device address

    esp_bt_uuid_t sdp_uuid

      Service uuid

    int record_count

      Number of SDP records

    esp_bluetooth_sdp_record_t *records

      SDP records

### Structures

struct esp_sdp_protocol_status_t

  SDP protocol status parameters.

  Public Members

  bool sdp_inited

    SDP initialization

  uint8_t records_num

    Number of created records

struct bluetooth_sdp_hdr_overlay

  SDP header structure.

  Public Members

  esp_bluetooth_sdp_types_t type

    SDP type

  esp_bt_uuid_t uuid

    UUID type, include uuid and uuid length, only needed to be set for RAW record creation

  uint32_t service_name_length

    Service name length

  char *service_name

    Service name

  int32_t rfcomm_channel_number

    RFCOMM channel number, if not used set to -1

  int32_t l2cap_psm

    L2CAP psm, if not used set to -1

  int32_t profile_version

    Profile version

  int user1_ptr_len

    User data1 length, only used for searching RAW record

  uint8_t *user1_ptr

    User data1 pointer to the raw SDP response data, only used for searching RAW record

struct bluetooth_sdp_raw_record

  Raw SDP record.

  Public Members

  esp_bluetooth_sdp_hdr_overlay_t hdr

    General info

struct bluetooth_sdp_mas_record

  Message Access Profile - Server parameters.

  Public Members

  esp_bluetooth_sdp_hdr_overlay_t hdr

    General info

  uint32_t mas_instance_id

    MAS Instance ID

  uint32_t supported_features

    Map supported features

  uint32_t supported_message_types

    Supported message types

struct bluetooth_sdp_mns_record

  Message Access Profile - Client (Notification Server) parameters.

  Public Members

  esp_bluetooth_sdp_hdr_overlay_t hdr

    General info

  uint32_t supported_features

    Supported features

struct bluetooth_sdp_pse_record

  Phone Book Profile - Server parameters.

  Public Members

  esp_bluetooth_sdp_hdr_overlay_t hdr

    General info

  uint32_t supported_features

    PBAP Supported Features

  uint32_t supported_repositories

    Supported Repositories

struct bluetooth_sdp_pce_record

  Phone Book Profile - Client parameters.

  Public Members

  esp_bluetooth_sdp_hdr_overlay_t hdr

    General info

struct bluetooth_sdp_ops_record

  Object Push Profile parameters.

  Public Members

  esp_bluetooth_sdp_hdr_overlay_t hdr

    General info

  int supported_formats_list_len

    Supported formats list length

  uint8_t supported_formats_list[SDP_OPP_SUPPORTED_FORMATS_MAX_LENGTH]

    Supported formats list

struct bluetooth_sdp_sap_record

  SIM Access Profile parameters.

  Public Members

  esp_bluetooth_sdp_hdr_overlay_t hdr

    General info

struct bluetooth_sdp_dip_record

  Device Identification Profile parameters.

  Note

  Only one primary Device Identification service record can be added in the SDP database. If primary Device Identification service is created multiple times, only the last one will take effect.

  Public Members

  esp_bluetooth_sdp_hdr_overlay_t hdr

    General info

  uint16_t vendor

    Vendor ID

  uint16_t vendor_id_source

    Vendor ID source, 0x0001 for Bluetooth, 0x0002 for USB, other values reserved, see `esp_sdp_vendor_id_source_t`

  uint16_t product

    Product ID

  uint16_t version

    Release version in format 0xJJMN(JJ – major number, M – minor number, N – sub-minor number)

  bool primary_record

    Indicate if the record is primary, shall set to true if there is a only single device record, others shall be set to false

### Macros

ESP_SDP_SERVER_NAME_MAX

  Service name max length

SDP_OPP_SUPPORTED_FORMATS_MAX_LENGTH

  OPP supported format list maximum length

ESP_SDP_UUID_MAP_MAS

  Message Access Service UUID

ESP_SDP_UUID_MAP_MNS

  Message Notification Service UUID

ESP_SDP_UUID_PBAP_PSE

  Phone Book Server Equipment UUID

ESP_SDP_UUID_PBAP_PCE

  Phone Book Client Equipment UUID

ESP_SDP_UUID_OPP

  Object Push Profile UUID

ESP_SDP_UUID_SAP

  SIM Access Profile UUID

ESP_SDP_UUID_DIP

  Device Identification Profile UUID

ESP_SDP_BUILD_BT_UUID16(uuid16_val)

  Build a Bluetooth UUID16.

### Type Definitions

typedef struct bluetooth_sdp_hdr_overlay esp_bluetooth_sdp_hdr_overlay_t

  SDP header structure.

typedef struct bluetooth_sdp_raw_record esp_bluetooth_sdp_raw_record_t

  Raw SDP record.

typedef struct bluetooth_sdp_mas_record esp_bluetooth_sdp_mas_record_t

  Message Access Profile - Server parameters.

typedef struct bluetooth_sdp_mns_record esp_bluetooth_sdp_mns_record_t

  Message Access Profile - Client (Notification Server) parameters.

typedef struct bluetooth_sdp_pse_record esp_bluetooth_sdp_pse_record_t

  Phone Book Profile - Server parameters.

typedef struct bluetooth_sdp_pce_record esp_bluetooth_sdp_pce_record_t

  Phone Book Profile - Client parameters.

typedef struct bluetooth_sdp_ops_record esp_bluetooth_sdp_ops_record_t

  Object Push Profile parameters.

typedef struct bluetooth_sdp_sap_record esp_bluetooth_sdp_sap_record_t

  SIM Access Profile parameters.

typedef struct bluetooth_sdp_dip_record esp_bluetooth_sdp_dip_record_t

  Device Identification Profile parameters.

  Note

  Only one primary Device Identification service record can be added in the SDP database. If primary Device Identification service is created multiple times, only the last one will take effect.

typedef void (*esp_sdp_cb_t)(esp_sdp_cb_event_t event, esp_sdp_cb_param_t *param)

  SDP callback function type.

  Param event:

    [in] Event type

  Param param:

    [in] Point to callback parameter, currently is union type

### Enumerations

enum esp_sdp_status_t

  SDP status parameters.

  Values:

  enumerator ESP_SDP_SUCCESS

    Successful operation.

  enumerator ESP_SDP_FAILURE

    Generic failure.

  enumerator ESP_SDP_NO_RESOURCE

    No more resource

  enumerator ESP_SDP_NEED_INIT

    SDP module shall init first

  enumerator ESP_SDP_NEED_DEINIT

    SDP module shall deinit first

  enumerator ESP_SDP_NO_CREATE_RECORD

    No record created

enum esp_sdp_cb_event_t

  SDP callback function events.

  Values:

  enumerator ESP_SDP_INIT_EVT

    When SDP is initialized, the event comes

  enumerator ESP_SDP_DEINIT_EVT

    When SDP is de-initialized, the event comes

  enumerator ESP_SDP_SEARCH_COMP_EVT

    When SDP search complete, the event comes

  enumerator ESP_SDP_CREATE_RECORD_COMP_EVT

    When create SDP records complete, the event comes

  enumerator ESP_SDP_REMOVE_RECORD_COMP_EVT

    When remove a SDP record complete, the event comes

enum esp_bluetooth_sdp_types_t

  SDP record type.

  Values:

  enumerator ESP_SDP_TYPE_RAW

    Used to carry raw SDP search data for unknown UUIDs

  enumerator ESP_SDP_TYPE_MAP_MAS

    Message Access Profile - Server

  enumerator ESP_SDP_TYPE_MAP_MNS

    Message Access Profile - Client (Notification Server)

  enumerator ESP_SDP_TYPE_PBAP_PSE

    Phone Book Profile - Server

  enumerator ESP_SDP_TYPE_PBAP_PCE

    Phone Book Profile - Client

  enumerator ESP_SDP_TYPE_OPP_SERVER

    Object Push Profile

  enumerator ESP_SDP_TYPE_SAP_SERVER

    SIM Access Profile

  enumerator ESP_SDP_TYPE_DIP_SERVER

    Device Identification Profile

enum esp_sdp_vendor_id_source_t

  Vendor ID source.

  Values:

  enumerator ESP_SDP_VENDOR_ID_SRC_BT

    Bluetooth assigned vendor id source

  enumerator ESP_SDP_VENDOR_ID_SRC_USB

    USB assigned vendor id source

Was this page helpful?

- Thank you! We received your feedback.
- If you have any comments, fill in Espressif Documentation Feedback Form.

- We value your feedback.
- Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.