mirror/MuditaOS
1
0
Fork 0
mirror of https://github.com/mudita/MuditaOS.git synced 2026-07-04 21:27:30 -04:00
Code Issues Packages Projects Releases Wiki Activity
Files
f7c8af86c858cd03142f62d582ef6461ba2168db
MuditaOS/module-bluetooth/lib/Bluetopia/profiles/PBAP/include/PBAPAPI.h

1306 lines
73 KiB
C
Raw Blame History

/*
* Copyright 2007 - 2014 Stonestreet One.
* All Rights Reserved.
* Author: Josh Toole
*** MODIFICATION HISTORY ****************************************************
*
* mm/dd/yy F. Lastname Description of Modification
* -------- ----------- ------------------------------------------------
* 12/18/07 J. Toole Initial creation.
****************************************************************************
*/
/**
* @file PBAPAPI.h
*
* @brief Stonestreet One Bluetooth Phone Book Access Profile (Version 1.0) API Type
* Definitions, Constants, and Prototypes.
*
* The PBAP interface provides APIs, data types,
* and macros. The header file should be included in an application as
* follows:
*
* @code
* #include "SS1BTPBA.h"
* @endcode
*
* The Phone Book Access Profile, PBAP, programming interface defines the
* protocols and procedures to be used to implement PBAP capabilities
* for both Server and Client services.
*
* ============================================================================
*/
#ifndef __PBAPAPIH__
#define __PBAPAPIH__
#include "SS1BTPS.h"
/*! Bluetooth Stack API Prototypes/Constants. */
/*! Error Return Codes.
* Error Codes that are smaller than these (less than -1000) are
* related to the Bluetooth Protocol Stack itself (see BTERRORS.H).
*/
#define BTPBAP_ERROR_INVALID_PARAMETER (-1000)
#define BTPBAP_ERROR_NOT_INITIALIZED (-1001)
#define BTPBAP_ERROR_INVALID_BLUETOOTH_STACK_ID (-1002)
#define BTPBAP_ERROR_LIBRARY_INITIALIZATION_ERROR (-1003)
#define BTPBAP_ERROR_INSUFFICIENT_RESOURCES (-1004)
#define BTPBAP_ERROR_REQUEST_ALREADY_OUTSTANDING (-1005)
#define BTPBAP_ERROR_ACTION_NOT_ALLOWED (-1006)
/* SDP Service Classes for the Phonebook Access Profile.
* The following MACRO is a utility MACRO that assigns the PBAP
* Profile ID Bluetooth Universally Unique Identifier to the
* specified UUID_16_t variable. This MACRO accepts one parameter
* which is the UUID_16_t variable that is to receive the Constant
* value.
*/
#define SDP_ASSIGN_PBAP_PROFILE_UUID_16(_x) ASSIGN_SDP_UUID_16((_x), 0x11, 0x30)
/*! The following MACRO is a utility MACRO that assigns the PBAP
* Profile ID Bluetooth Universally Unique Identifier to the
* specified UUID_32_t variable. This MACRO accepts one parameter
* which is the UUID_32_t variable that is to receive the Constant
* value.
*/
#define SDP_ASSIGN_PBAP_PROFILE_UUID_32(_x) ASSIGN_SDP_UUID_32((_x), 0x00, 0x00, 0x11, 0x30)
/*! The following MACRO is a utility MACRO that assigns the PBAP
* Profile ID Bluetooth Universally Unique Identifier to the
* specified UUID_128_t variable. This MACRO accepts one parameter
* which is the UUID_128_t variable that is to receive the Constant
* value.
*/
#define SDP_ASSIGN_PBAP_PROFILE_UUID_128(_x) ASSIGN_SDP_UUID_128((_x), 0x00, 0x00, 0x11, 0x30, 0x00, 0x00, 0x10, 0x00, 0x80, 0x00, 0x00, 0x80, 0x5F, 0x9B, 0x34, 0xFB)
/* SDP Service Classes for the Phonebook Access Profile.
* The following MACRO is a utility MACRO that assigns the PBAP
* Profile Client Bluetooth Universally Unique Identifier to the
* specified UUID_16_t variable. This MACRO accepts one parameter
* which is the UUID_16_t variable that is to receive the Constant
* value.
*/
#define SDP_ASSIGN_PBAP_CLIENT_UUID_16(_x) ASSIGN_SDP_UUID_16((_x), 0x11, 0x2E)
/*! The following MACRO is a utility MACRO that assigns the PBAP
* Profile Client Bluetooth Universally Unique Identifier to the
* specified UUID_32_t variable. This MACRO accepts one parameter
* which is the UUID_32_t variable that is to receive the Constant
* value.
*/
#define SDP_ASSIGN_PBAP_CLIENT_UUID_32(_x) ASSIGN_SDP_UUID_32((_x), 0x00, 0x00, 0x11, 0x2E)
/*! The following MACRO is a utility MACRO that assigns the PBAP
* Profile Client Bluetooth Universally Unique Identifier to the
* specified UUID_128_t variable. This MACRO accepts one parameter
* which is the UUID_128_t variable that is to receive the Constant
* value.
*/
#define SDP_ASSIGN_PBAP_CLIENT_UUID_128(_x) ASSIGN_SDP_UUID_128((_x), 0x00, 0x00, 0x11, 0x2E, 0x00, 0x00, 0x10, 0x00, 0x80, 0x00, 0x00, 0x80, 0x5F, 0x9B, 0x34, 0xFB)
/*! The following MACRO is a utility MACRO that assigns the PBAP
* Profile Server Bluetooth Universally Unique Identifier to the
* specified UUID_16_t variable. This MACRO accepts one parameter
* which is the UUID_16_t variable that is to receive the Constant
* value.
*/
#define SDP_ASSIGN_PBAP_SERVER_UUID_16(_x) ASSIGN_SDP_UUID_16((_x), 0x11, 0x2F)
/*! The following MACRO is a utility MACRO that assigns the PBAP
* Profile Server Bluetooth Universally Unique Identifier to the
* specified UUID_32_t variable. This MACRO accepts one parameter
* which is the UUID_32_t variable that is to receive the Constant
* value.
*/
#define SDP_ASSIGN_PBAP_SERVER_UUID_32(_x) ASSIGN_SDP_UUID_32((_x), 0x00, 0x00, 0x11, 0x2F)
/*! The following MACRO is a utility MACRO that assigns the PBAP
* Profile Server Bluetooth Universally Unique Identifier to the
* specified UUID_128_t variable. This MACRO accepts one parameter
* which is the UUID_128_t variable that is to receive the Constant
* value.
*/
#define SDP_ASSIGN_PBAP_SERVER_UUID_128(_x) ASSIGN_SDP_UUID_128((_x), 0x00, 0x00, 0x11, 0x2F, 0x00, 0x00, 0x10, 0x00, 0x80, 0x00, 0x00, 0x80, 0x5F, 0x9B, 0x34, 0xFB)
/*! The following definitions represent the defined Supported
* Repositories that can be supported by a PBAP Server. These SDP
* Definitions are used with the Bluetooth Supported Repositories
* Attribute.
*/
#define SDP_PBAP_SUPPORTED_REPOSITORIES_LOCAL_PHONEBOOK 0x01
#define SDP_PBAP_SUPPORTED_REPOSITORIES_SIM_CARD_PHONEBOOK 0x02
/*! The following constants represent the Minimum and Maximum Port
* Numbers that can be opened (both locally and remotely). These
* constants specify the range for the Port Number parameters in the
* Open Functions.
*/
#define PBAP_PORT_NUMBER_MINIMUM (SPP_PORT_NUMBER_MINIMUM)
#define PBAP_PORT_NUMBER_MAXIMUM (SPP_PORT_NUMBER_MAXIMUM)
/*! The following constants are the OBEX response codes that are
* specifically allowed in the PBAP specification. The error codes
* for Not Found, Service Unavailable, Bad Request, and Not
* Implemented are all specifically mandatory. All others listed
* here are optional. Other OBEX error codes not listed here are
* specifically DISALLOWED by the specification.
*/
#define PBAP_OBEX_RESPONSE_CONTINUE (OBEX_CONTINUE_RESPONSE)
#define PBAP_OBEX_RESPONSE_OK (OBEX_OK_RESPONSE)
#define PBAP_OBEX_RESPONSE_NOT_FOUND (OBEX_NOT_FOUND_RESPONSE)
#define PBAP_OBEX_RESPONSE_SERVICE_UNAVAILABLE (OBEX_SERVICE_UNAVAILABLE_RESPONSE)
#define PBAP_OBEX_RESPONSE_BAD_REQUEST (OBEX_BAD_REQUEST_RESPONSE)
#define PBAP_OBEX_RESPONSE_NOT_IMPLEMENTED (OBEX_NOT_IMPLEMENTED_RESPONSE)
#define PBAP_OBEX_RESPONSE_UNAUTHORIZED (OBEX_UNAUTHORIZED_RESPONSE)
#define PBAP_OBEX_RESPONSE_PRECONDITION_FAILED (OBEX_PRECONDITION_FAILED_RESPONSE)
#define PBAP_OBEX_RESPONSE_NOT_ACCEPTABLE (OBEX_NOT_ACCEPTABLE_RESPONSE)
#define PBAP_OBEX_RESPONSE_FORBIDDEN (OBEX_FORBIDDEN_RESPONSE)
/*! The following define the OBEX Response Final Bit to be appended to
* the response codes passed into function of this module.
*/
#define PBAP_OBEX_RESPONSE_FINAL_BIT (OBEX_FINAL_BIT)
/*! The following BIT definitions are used to denote the possible PBAP
* Profile Server Modes that can be applied to a PBAP Profile Client
* Connection. These BIT definitions are used with the
* PBAP_Set_Server_Mode() and PBAP_Get_Server_Mode() mode functions.
*/
#define PBAP_SERVER_MODE_AUTOMATIC_ACCEPT_CONNECTION (0x00000000)
#define PBAP_SERVER_MODE_MANUAL_ACCEPT_CONNECTION (0x00000001)
/*! The following BIT MASK is used to mask the Server Mode Accept
* Connection settings from other (undefined) Server Mode bits.
*/
#define PBAP_SERVER_MODE_CONNECTION_MASK (0x00000001)
/*! The following constants represent the PBAP Profile Status Values
* that are possible in the PBAP Profile Connect Confirmation Event.
*/
#define PBAP_OPEN_STATUS_SUCCESS (0x00)
#define PBAP_OPEN_STATUS_CONNECTION_TIMEOUT (0x01)
#define PBAP_OPEN_STATUS_CONNECTION_REFUSED (0x02)
#define PBAP_OPEN_STATUS_UNKNOWN_ERROR (0x04)
/*! The following constant defines the PBAP Profile version included
* in the SDP record for the PBAP profile, as specified in the
* relevant specification.
*/
#define PBAP_PROFILE_VERSION (0x0100)
/*! The following constants define the Supported Repositories that are
* able to be supported by this profile. These values are used with
* the PBAP_Open_Server_Port() function.
*/
#define PBAP_SUPPORTED_REPOSITORIES_LOCAL_PHONEBOOK (SDP_PBAP_SUPPORTED_REPOSITORIES_LOCAL_PHONEBOOK)
#define PBAP_SUPPORTED_REPOSITORIES_SIM_CARD_PHONEBOOK (SDP_PBAP_SUPPORTED_REPOSITORIES_SIM_CARD_PHONEBOOK)
/*! The following defines specify the bit locations for the 64-bit
* filter field specified by the PBAP Profile specification. Each of
* these bits can be OR'ed together to form a filter mask that should
* be passed in the FilterLow parameter where a filter is required.
* The FilterHigh portion contains proprietary filter settings, if
* these are not used it should be set to zero. Refer to the PBAP
* specification for more information.
*/
#define PBAP_FILTER_VERSION (1 << 0)
#define PBAP_FILTER_FN (1 << 1)
#define PBAP_FILTER_N (1 << 2)
#define PBAP_FILTER_PHOTO (1 << 3)
#define PBAP_FILTER_BDAY (1 << 4)
#define PBAP_FILTER_ADR (1 << 5)
#define PBAP_FILTER_LABEL (1 << 6)
#define PBAP_FILTER_TEL (1 << 7)
#define PBAP_FILTER_EMAIL (1 << 8)
#define PBAP_FILTER_MAILER (1 << 9)
#define PBAP_FILTER_TZ (1 << 10)
#define PBAP_FILTER_GEO (1 << 11)
#define PBAP_FILTER_TITLE (1 << 12)
#define PBAP_FILTER_ROLE (1 << 13)
#define PBAP_FILTER_LOGO (1 << 14)
#define PBAP_FILTER_AGENT (1 << 15)
#define PBAP_FILTER_ORG (1 << 16)
#define PBAP_FILTER_NOTE (1 << 17)
#define PBAP_FILTER_REV (1 << 18)
#define PBAP_FILTER_SOUND (1 << 19)
#define PBAP_FILTER_URL (1 << 20)
#define PBAP_FILTER_UID (1 << 21)
#define PBAP_FILTER_KEY (1 << 22)
#define PBAP_FILTER_NICKNAME (1 << 23)
#define PBAP_FILTER_CATEGORIES (1 << 24)
#define PBAP_FILTER_PROID (1 << 25)
#define PBAP_FILTER_CLASS (1 << 26)
#define PBAP_FILTER_SORT_STRING (1 << 27)
#define PBAP_FILTER_X_IRMC_CALL_DATETIME (1 << 28)
#define PBAP_FILTER_NONE (0)
#define PBAP_FILTER_ALL ((1 << 29)-1)
#define PBAP_FILTER_VCARD21_MINIMUM (PBAP_FILTER_VERSION | PBAP_FILTER_N | PBAP_FILTER_TEL)
#define PBAP_FILTER_VCARD30_MINIMUM (PBAP_FILTER_VERSION | PBAP_FILTER_N | PBAP_FILTER_FN | PBAP_FILTER_TEL)
/*! The following define specifies the bit location for the
* Proprietary Filter bit for the 64-bit Filter bit mask. Because
* this implementation handles this 64-bit field as two 32-bit
* fields, this bit position has been shifted for use in the
* FilterHigh parameter only. If a Proprietary Filter is NOT used,
* the entire FilterHigh parameter should be set to ZERO. Bits 40-63
* (shifted by 32 for the FilterHigh parameter) are available for
* defining proprietary filter bits. Refer to the PBAP specification
* for more information.
*/
#define PBAP_FILTER_PROPRIETARY_FILTER_HIGH (1 << (39-32))
/*! The following define is the value that is used for the
* MaxListCount header to indicate that there is not a restriction of
* the number of items that can be returned. This is also the
* default value if this header is not present.
*/
#define PBAP_MAX_LIST_COUNT_NOT_RESTRICTED (65535)
/*! The following definition defines the delimiter character that is
* used to delimit the individual sub-paths in a fully qualified path
* name.
*/
#define PBAP_PATH_DELIMETER_CHARACTER '/'
/*! The following definition defines the path immediately off of the
* root either (main root or SIM root) that contains the PBAP
* Information Store.
*/
#define PBAP_TELECOM_PATH_NAME "telecom"
/*! The following constant presents the path (off of main/absolute
* root) that contains the PBAP Information Store that is present on
* an external SIM Card (as opposed to stored on the phone directly).
*/
#define PBAP_SIM_PATH_NAME "SIM"
/*! The following constants present the path names of all required
* paths under the PBAP_TELECOM_PATH_NAME that hold the various PBAP
* Information Stores.
* \note These path names can also be used as a prefix to fetch
* an entire store. For example, if the caller was
* currently operating in the PBAP_TELECOM_PATH_NAME path
* (/telecom), the fetching the object
* PBAP_PHONEBOOK_PATH_NAME appended with ".vcf" (pb.vcf)
* would fetch the entire phonebook.
*/
#define PBAP_PHONEBOOK_PATH_NAME "pb"
#define PBAP_INCOMING_CALL_HISTORY_PATH_NAME "ich"
#define PBAP_OUTGOING_CALL_HISTORY_PATH_NAME "och"
#define PBAP_MISSED_CALL_HISTORY_PATH_NAME "mch"
#define PBAP_COMBINED_CALL_HISTORY_PATH_NAME "cch"
/*! The following enumeration is a list of the valid operations that
* can be performed using the PBAP_Set_Phonebook operation. This
* correspond to flag settings for the OBEX SetPath command.
*/
typedef enum
{
spRoot,
spDown,
spUp
} PBAP_Set_Path_Option_t;
/*! The following enumeration is a list of valid format values that
* can be used when pulling vCards from a remote PBAP server.
*/
typedef enum
{
pfvCard21,
pfvCard30,
pfDefault
} PBAP_Format_t;
/*! The following enumeration is a list of the valid Listing order
* types that can be sent/received in the Pull vCard Listing request.
*/
typedef enum
{
loIndexed,
loAlphabetical,
loPhonetical,
loDefault
} PBAP_List_Order_t;
/*! The following enumeration is a list of the valid search attributes
* that can be specified in a Pull vCard Listing request.
*/
typedef enum
{
saName,
saNumber,
saSound,
saDefault
} PBAP_Search_Attribute_t;
/*! The following enumeration covers all the events generated by the
* PBAP Profile. These are used to determine the type of each event
* generated, and to ensure the proper union element is accessed for
* the PBAP_Event_Data_t structure.
*/
typedef enum
{
etPBAP_Open_Port_Indication, /*!< Dispatched when a PBAP client connects to a local PBAP Server. */
etPBAP_Open_Port_Confirmation, /*!< Dispatched when a PBAP client receives a connection response from a remote PBAP Server to which it previously attempted to connect. */
etPBAP_Open_Port_Request_Indication, /*!< Dispatched when a PBAP client requests a connection to a local PBAP Server. This event only occurs if the local server is in Manual Accept mode. */
etPBAP_Close_Port_Indication, /*!< Dispatched when a PBAP Server or Client connection has been disconnected from either end. */
etPBAP_Abort_Indication, /*!< Dispatched when the local PBAP Server receives an OBEX Abort Request from the remote Client. */
etPBAP_Abort_Confirmation, /*!< Dispatched when the local PBAP Client receives an OBEX Abort Response from the remote Server. */
etPBAP_Pull_Phonebook_Indication, /*!< Dispatched when the local PBAP Server receives a Pull Phonebook Request. */
etPBAP_Pull_Phonebook_Confirmation, /*!< Dispatched when the local PBAP Client receives a Pull Phonebook Response. */
etPBAP_Set_Phonebook_Indication, /*!< Dispatched when the local PBAP Server receives a Set Phonebook Request. */
etPBAP_Set_Phonebook_Confirmation, /*!< Dispatched when the local PBAP Client receives a Set Phonebook Response. */
etPBAP_Pull_vCard_Listing_Indication, /*!< Dispatched when the local PBAP Server receives a Pull vCard Listing Request. */
etPBAP_Pull_vCard_Listing_Confirmation, /*!< Dispatched when the local PBAP Client receives a Pull vCard LIsting Response. */
etPBAP_Pull_vCard_Entry_Indication, /*!< Dispatched when the local PBAP Server receives a Pull vCard Entry Request. */
etPBAP_Pull_vCard_Entry_Confirmation /*!< Dispatched when the local PBAP Client receives a Pull vCard Entry Response. */
} PBAP_Event_Type_t;
/*! The following PBAP Profile Event is dispatched when a PBAP Profile
* Client Connects to a local PBAP Profile Server. The PBAP ID
* member specifies the local Server that has been connected to and
* the BD_ADDR member specifies the Client Bluetooth Device that has
* connected to the specified Server.
*/
typedef struct _tagPBAP_Open_Port_Indication_Data_t
{
unsigned int PBAPID;
BD_ADDR_t BD_ADDR;
} PBAP_Open_Port_Indication_Data_t;
#define PBAP_OPEN_PORT_INDICATION_DATA_SIZE (sizeof(PBAP_Open_Port_Indication_Data_t))
/*! The following PBAP Profile Event is dispatched when a PBAP Client
* receives the Connection Response from a remote PBAP Profile Server
* to which it has previously attempted to connect. The PBAP Profile
* ID member specifies the local Client that requested the
* connection, the PBAP Profile Connect Status represents the
* Connection Status of the Request, and the BD_ADDR member specifies
* the Bluetooth Device Address of the remote Bluetooth PBAP Profile
* Server.
*/
typedef struct _tagPBAP_Open_Port_Confirmation_Data_t
{
unsigned int PBAPID;
unsigned int PBAPConnectStatus;
BD_ADDR_t BD_ADDR;
} PBAP_Open_Port_Confirmation_Data_t;
#define PBAP_OPEN_PORT_CONFIRMATION_DATA_SIZE (sizeof(PBAP_Open_Port_Confirmation_Data_t))
/*! The following PBAP Profile Event is dispatched when a PBAP Profile
* Client requests a connection to a local PBAP Profile Server. The
* PBAP ID member specifies the local Server that has received the
* request to connect and the BD_ADDR member specifies the Client
* Bluetooth Device that is requesting to connect to the specified
* Server.
* \note This event is only dispatched to servers that are in
* Manual Accept Mode.
* \note This event must be responded to with the
* PBAP_Open_Request_Response() function in order to
* accept or reject the outstanding Open Request.
*/
typedef struct _tagPBAP_Open_Port_Request_Indication_Data_t
{
unsigned int PBAPID;
unsigned int ServerPort;
BD_ADDR_t BD_ADDR;
} PBAP_Open_Port_Request_Indication_Data_t;
#define PBAP_OPEN_PORT_REQUEST_INDICATION_DATA_SIZE (sizeof(PBAP_Open_Port_Request_Indication_Data_t))
/*! The following PBAP Profile Event is dispatched when a PBAP Profile
* Server or Client connection is disconnected. The PBAP ID member
* specifies the local connection from which the remote device has
* disconnected.
*/
typedef struct _tagPBAP_Close_Port_Indication_Data_t
{
unsigned int PBAPID;
} PBAP_Close_Port_Indication_Data_t;
#define PBAP_CLOSE_PORT_INDICATION_DATA_SIZE (sizeof(PBAP_Close_Port_Indication_Data_t))
/*! The following PBAP Profile Event is dispatched when a PBAP Profile
* Abort Request is received from a remote PBAP Profile Client. The
* PBAP ID member specifies the local Server that has received the
* request.
* \note When receiving this indication, the PBAP profile has
* already automatically dispatched a response to the remote
* client.
*/
typedef struct _tagPBAP_Abort_Indication_Data_t
{
unsigned int PBAPID;
} PBAP_Abort_Indication_Data_t;
#define PBAP_ABORT_INDICATION_DATA_SIZE (sizeof(PBAP_Abort_Indication_Data_t))
/*! The following PBAP Profile Event is dispatched when a PBAP Profile
* Abort Response is received from a remote PBAP Profile Server. The
* PBAP ID member specifies the local Client that has received the
* response.
*/
typedef struct _tagPBAP_Abort_Confirmation_Data_t
{
unsigned int PBAPID;
} PBAP_Abort_Confirmation_Data_t;
#define PBAP_ABORT_CONFIRMATION_DATA_SIZE (sizeof(PBAP_Abort_Confirmation_Data_t))
/*! The following PBAP Profile Event is dispatched when an PBAP Server
* receives a Pull Phonebook Request from a remote PBAP Client. The
* PBAP ID member specifies the local Server that has received the
* request. The ObjectName member contains the Name/Path of the
* Phonebook being requested by this Pull Phonebook operation. The
* FilterLow parameter contains the lower 32 bits of the 64-bit
* filter attribute. The FilterHigh parameter contains the higher 32
* bits of the 64-bit filter attribute. The Format parameter is an
* enumeration which specifies the vCard format requested in this
* Pull Phonebook request. The MaxListCount parameter is an unsigned
* integer that specifies the maximum number of entries the
* requesting client can handle. A value of 65535 means that the
* number of entries is not restricted. A MaxListCount of ZERO (0)
* indicates that the Client is requesting the number of used indexes
* in the Phonebook specified by the ObjectName parameter. In this
* case the response should return the PhonebookSize and other
* parameters in this event can be ignored. If MaxListCount is
* non-zero then the ListStartOffset parameter specifies the index
* requested by the Client in this PullPhonebookRequest. This value
* defaults to zero if not provided by the Client.
*/
typedef struct _tagPBAP_Pull_Phonebook_Indication_Data_t
{
unsigned int PBAPID;
char *ObjectName;
DWord_t FilterLow;
DWord_t FilterHigh;
PBAP_Format_t Format;
Word_t MaxListCount;
Word_t ListStartOffset;
} PBAP_Pull_Phonebook_Indication_Data_t;
#define PBAP_PULL_PHONEBOOK_INDICATION_DATA_SIZE (sizeof(PBAP_Pull_Phonebook_Indication_Data_t))
/*! The following PBAP Profile Event is dispatched when an PBAP Client
* receives a Pull Phonebook Response from a remote PBAP Server. The
* PBAP ID member specifies the local client that has received the
* response. The ResponseCode member contains the response code
* included in the response packet. The BufferSize and Buffer
* members contain the size and pointer (respectively) for the vCard
* data included in this Pull Phonebook Response. The Final member
* indicates if this is the last block of data that will be sent in
* the Pull Phonebook transaction (Final = TRUE if Server sent
* EndOfBody header). The PhonebookSize parameter is only valid if
* the original request was for the PhonebookSize. In this case,
* this parameter will contain the Phonebook size returned by the
* PBAP server. Otherwise this parameter will be set to zero. The
* NewMissedCalls parameter is only valid if the "mch" Phonebook was
* requested. In this case, this parameter contains the number of
* new missed calls which have not been checked on the server.
* Otherwise this parameter will default to zero.
*/
typedef struct _tagPBAP_Pull_Phonebook_Confirmation_Data_t
{
unsigned int PBAPID;
Byte_t ResponseCode;
unsigned int BufferSize;
Byte_t *Buffer;
Boolean_t Final;
Word_t PhonebookSize;
Byte_t NewMissedCalls;
} PBAP_Pull_Phonebook_Confirmation_Data_t;
#define PBAP_PULL_PHONEBOOK_CONFIRMATION_DATA_SIZE (sizeof(PBAP_Pull_Phonebook_Confirmation_Data_t))
/*! The following PBAP Profile Event is dispatched when an PBAP Server
* receives a Set Phonebook Request from a remote PBAP Client. The
* PBAP ID member specifies the local Server that has received the
* request. The PathOption parameter contains an enumerated value
* that indicates the type of path change being requested. The
* ObjectName member contains the Name/Path of the Phonebook being
* requested by this Set Phonebook operation.
*/
typedef struct _tagPBAP_Set_Phonebook_Indication_Data_t
{
unsigned int PBAPID;
PBAP_Set_Path_Option_t PathOption;
char *ObjectName;
} PBAP_Set_Phonebook_Indication_Data_t;
#define PBAP_SET_PHONEBOOK_INDICATION_DATA_SIZE (sizeof(PBAP_Set_Phonebook_Indication_Data_t))
/*! The following PBAP Profile Event is dispatched when an PBAP Client
* receives a Set Phonebook Response from a remote PBAP Server. The
* PBAP ID member specifies the local client that has received the
* response. The ResponseCode member contains the response code
* included in the response packet.
*/
typedef struct _tagPBAP_Set_Phonebook_Confirmation_Data_t
{
unsigned int PBAPID;
Byte_t ResponseCode;
} PBAP_Set_Phonebook_Confirmation_Data_t;
#define PBAP_SET_PHONEBOOK_CONFIRMATION_DATA_SIZE (sizeof(PBAP_Set_Phonebook_Confirmation_Data_t))
/*! The following PBAP Profile Event is dispatched when an PBAP Server
* receives a Pull vCard Listing Request from a remote PBAP Client.
* The PBAP ID member specifies the local Server that has received
* the request. The ObjectName member contains the folder being
* requested by this Pull vCard Listing operation. If this value is
* NULL the current directory should be retrieved. The ListOrder
* parameter is an enumerated type that determines the desired order
* of the requested listing. The SearchAttribute is an enumerated
* type that determines the requested attribute used to filter this
* request. The SearchValue parameter contains an ASCII,
* Null-terminated character string that contains the string request
* for search/filter. If this parameter is NULL, no search/filter
* was specified in the request. The MaxListCount parameter is an
* unsigned integer that specifies the maximum number of entries the
* requesting client can handle. A value of 65535 means that the
* number of entries is not restricted. A MaxListCount of ZERO (0)
* indicates that the Client is requesting the number of used indexes
* in the folder specified by the ObjectName parameter. In this case
* the response should return the PhonebookSize and other parameters
* in this event can be ignored. If MaxListCount is non-zero then
* the ListStartOffset parameter specifies the index requested by the
* Client in this Pull vCard Listing. This value defaults to zero if
* not provided by the Client.
*/
typedef struct _tagPBAP_Pull_vCard_Listing_Indication_Data_t
{
unsigned int PBAPID;
char *ObjectName;
PBAP_List_Order_t ListOrder;
PBAP_Search_Attribute_t SearchAttribute;
char *SearchValue;
Word_t MaxListCount;
Word_t ListStartOffset;
} PBAP_Pull_vCard_Listing_Indication_Data_t;
#define PBAP_PULL_VCARD_LISTING_INDICATION_DATA_SIZE (sizeof(PBAP_Pull_vCard_Listing_Indication_Data_t))
/*! The following PBAP Profile Event is dispatched when an PBAP Client
* receives a Pull vCard Listing Response from a remote PBAP Server.
* The PBAP ID member specifies the local client that has received
* the response. The ResponseCode member contains the response code
* included in the response packet. The BufferSize and Buffer
* members contain the size and pointer (respectively) for the vCard
* data included in this Pull vCard Listing Response. The Final
* member indicates if this is the last block of data that will be
* sent in the Pull vCard Listing transaction (Final = TRUE if Server
* sent EndOfBody header). The PhonebookSize parameter is only valid
* if the original request was for the PhonebookSize. In this case,
* this parameter will contain the Phonebook size returned by the
* PBAP server. Otherwise this parameter will be set to zero. The
* NewMissedCalls parameter is only valid if the "mch" Phonebook was
* requested. In this case, this parameter contains the number of
* new missed calls which have not been checked on the server.
* Otherwise this parameter will default to zero.
*/
typedef struct _tagPBAP_Pull_vCard_Listing_Confirmation_Data_t
{
unsigned int PBAPID;
Byte_t ResponseCode;
unsigned int BufferSize;
Byte_t *Buffer;
Boolean_t Final;
Word_t PhonebookSize;
Byte_t NewMissedCalls;
} PBAP_Pull_vCard_Listing_Confirmation_Data_t;
#define PBAP_PULL_VCARD_LISTING_CONFIRMATION_DATA_SIZE (sizeof(PBAP_Pull_vCard_Listing_Confirmation_Data_t))
/*! The following PBAP Profile Event is dispatched when an PBAP Server
* receives a Pull vCard Entry Request from a remote PBAP Client.
* The PBAP ID member specifies the local Server that has received
* the request. The ObjectName member contains the entry of the
* Phonebook being requested by this Pull vCard Entry operation. The
* FilterLow parameter contains the lower 32 bits of the 64-bit
* filter attribute. The FilterHigh parameter contains the higher 32
* bits of the 64-bit filter attribute. The Format parameter is an
* enumeration which specifies the vCard format requested in this
* Pull vCard Entry request.
*/
typedef struct _tagPBAP_Pull_vCard_Entry_Indication_Data_t
{
unsigned int PBAPID;
char *ObjectName;
DWord_t FilterLow;
DWord_t FilterHigh;
PBAP_Format_t Format;
} PBAP_Pull_vCard_Entry_Indication_Data_t;
#define PBAP_PULL_VCARD_ENTRY_INDICATION_DATA_SIZE (sizeof(PBAP_Pull_vCard_Entry_Indication_Data_t))
/*! The following PBAP Profile Event is dispatched when an PBAP Client
* receives a Pull vCard Entry Response from a remote PBAP Server.
* The PBAP ID member specifies the local client that has received
* the response. The ResponseCode member contains the response code
* included in the response packet. The BufferSize and Buffer
* members contain the size and pointer (respectively) for the vCard
* data included in this Pull vCard Entry Response. The Final member
* indicates if this is the last block of data that will be sent in
* the Pull vCard Entry transaction (Final = TRUE if Server sent
* EndOfBody header).
*/
typedef struct _tagPBAP_Pull_vCard_Entry_Confirmation_Data_t
{
unsigned int PBAPID;
Byte_t ResponseCode;
unsigned int BufferSize;
Byte_t *Buffer;
Boolean_t Final;
} PBAP_Pull_vCard_Entry_Confirmation_Data_t;
#define PBAP_PULL_VCARD_ENTRY_CONFIRMATION_DATA_SIZE (sizeof(PBAP_Pull_vCard_Entry_Confirmation_Data_t))
/*! The following structure represents the container structure for
* holding all PBAP Profile Event Data. This structure is received
* for each event generated. The Event_Data_Type member is used to
* determine the appropriate union member element to access the
* contained data. The Event_Data_Size member contains the total
* size of the data contained in this event.
*/
typedef struct _tagPBAP_Event_Data_t
{
PBAP_Event_Type_t Event_Data_Type;
Word_t Event_Data_Size;
union
{
PBAP_Open_Port_Indication_Data_t *PBAP_Open_Port_Indication_Data;
PBAP_Open_Port_Confirmation_Data_t *PBAP_Open_Port_Confirmation_Data;
PBAP_Open_Port_Request_Indication_Data_t *PBAP_Open_Port_Request_Indication_Data;
PBAP_Close_Port_Indication_Data_t *PBAP_Close_Port_Indication_Data;
PBAP_Abort_Indication_Data_t *PBAP_Abort_Indication_Data;
PBAP_Abort_Confirmation_Data_t *PBAP_Abort_Confirmation_Data;
PBAP_Pull_Phonebook_Indication_Data_t *PBAP_Pull_Phonebook_Indication_Data;
PBAP_Pull_Phonebook_Confirmation_Data_t *PBAP_Pull_Phonebook_Confirmation_Data;
PBAP_Set_Phonebook_Indication_Data_t *PBAP_Set_Phonebook_Indication_Data;
PBAP_Set_Phonebook_Confirmation_Data_t *PBAP_Set_Phonebook_Confirmation_Data;
PBAP_Pull_vCard_Listing_Indication_Data_t *PBAP_Pull_vCard_Listing_Indication_Data;
PBAP_Pull_vCard_Listing_Confirmation_Data_t *PBAP_Pull_vCard_Listing_Confirmation_Data;
PBAP_Pull_vCard_Entry_Indication_Data_t *PBAP_Pull_vCard_Entry_Indication_Data;
PBAP_Pull_vCard_Entry_Confirmation_Data_t *PBAP_Pull_vCard_Entry_Confirmation_Data;
} Event_Data;
} PBAP_Event_Data_t;
#define PBAP_EVENT_DATA_SIZE (sizeof(PBAP_Event_Data_t))
/*! The following declared type represents the Prototype Function for
* a PBAP Profile Event Receive Data Callback. This function will be
* called whenever an PBAP Profile Event occurs that is associated
* with the specified Bluetooth Stack ID. This function passes to
* the caller the Bluetooth Stack ID, the PBAP Event Data that
* occurred and the PBAP Profile Event Callback Parameter that was
* specified when this Callback was installed. The caller is free to
* use the contents of the PBAP Profile Event Data ONLY in the
* context of this callback. If the caller requires the Data for a
* longer period of time, then the callback function MUST copy the
* data into another Data Buffer This function is guaranteed NOT to
* be invoked more than once simultaneously for the specified
* installed callback (i.e. this function DOES NOT have be
* re-entrant). It needs to be noted however, that if the same
* Callback is installed more than once, then the callbacks will be
* called serially. Because of this, the processing in this function
* should be as efficient as possible. It should also be noted that
* this function is called in the Thread Context of a Thread that the
* User does NOT own. Therefore, processing in this function should
* be as efficient as possible (this argument holds anyway because
* another PBAP Profile Event will not be processed while this
* function call is outstanding).
* \note This function MUST NOT Block and wait for events that
* can only be satisfied by Receiving PBAP Profile Event
* Packets. A Deadlock WILL occur because NO PBAP Event
* Callbacks will be issued while this function is
* currently outstanding.
*/
typedef void (BTPSAPI *PBAP_Event_Callback_t)(unsigned int BluetoothStackID, PBAP_Event_Data_t *PBAP_Event_Data, unsigned long CallbackParameter);
/*! @brief The following function is responsible for opening a local PBAP
* Server. @param BluetoothStackID The first parameter is the Bluetooth Stack ID on which to
* open the server. @param ServerPort The second parameter is the Port on which to
* open this server, and *MUST* be between PBAP_PORT_NUMBER_MINIMUM
* and PBAP_PORT_NUMBER_MAXIMUM. @param SupportedRepositories The third parameter is a bitmask
* which determines which repositories are supported by this server
* instance. @param EventCallback The fourth parameter is the Callback function to call
* when an event occurs on this Server Port. @param CallbackParameter The final parameter is
* a user-defined callback parameter that will be passed to the
* callback function with each event. @return This function returns a
* positive, non zero value if successful or a negative return error
* code if an error occurs. A successful return code will be a PBAP
* Profile ID that can be used to reference the Opened PBAP Profile
* Server Port in ALL other PBAP Server functions in this module.
* Once an PBAP Profile Server is opened, it can only be
* Un-Registered via a call to the PBAP_Close_Server() function
* (passing the return value from this function).
*/
BTPSAPI_DECLARATION int BTPSAPI PBAP_Open_Server_Port(unsigned int BluetoothStackID, unsigned int ServerPort, Byte_t SupportedRepositories, PBAP_Event_Callback_t EventCallback, unsigned long CallbackParameter);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_PBAP_Open_Server_Port_t)(unsigned int BluetoothStackID, unsigned int ServerPort, Byte_t SupportedRepositories, PBAP_Event_Callback_t EventCallback, unsigned long CallbackParameter);
#endif
/*! @brief The following function is responsible for closing a PBAP Profile
* Server (which was opened by a successful call to the
* PBAP_Open_Server_Port() function). @param BluetoothStackID The first parameter is the
* Bluetooth Stack ID of the previously opened server port. @param PBAPID The second parameter is the PBAP ID returned from the previous call to
* PBAP_Open_Server_Port(). @return This function returns zero if
* successful, or a negative return error code if an error occurred
* (see BTERRORS.H). Note that this function does NOT delete any SDP
* Service Record Handles.
*/
BTPSAPI_DECLARATION int BTPSAPI PBAP_Close_Server_Port(unsigned int BluetoothStackID, unsigned int PBAPID);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_PBAP_Close_Server_Port_t)(unsigned int BluetoothStackID, unsigned int PBAPID);
#endif
/*! @brief The following function adds a PBAP Server (PSE) Service Record to
* the SDP Database. @param BluetoothStackID The first parameter is the Bluetooth Stack ID
* of the stack on which to register this SDP record. @param PBAPID The second parameter is the PBAP ID that was returned by a previous call to
* PBAP_Open_Server_Port(). @param ServiceName The third parameter is a pointer to
* ASCII, NULL terminated string containing the Service Name to
* include within the SDP Record. @param SDPServiceRecordHandle The final parameter is a pointer
* to a DWord_t which receives the SDP Service Record Handle if this
* function successfully creates an SDP Service Record. If @return This function returns zero, then the SDPServiceRecordHandle entry will
* contain the Service Record Handle of the added SDP Service Record.
* If this function fails, a negative return error code will be
* returned (see BTERRORS.H) and the SDPServiceRecordHandle value
* will be undefined.
* \note This function should only be called with the PBAP ID that
* was returned from the PBAP_Open_Server_Port() function.
* This function should NEVER be used with PBAP ID returned
* from the PBAP_Open_Remote_Server_Port() function.
* \note The Service Record Handle that is returned from this
* function will remain in the SDP Record Database until it
* is deleted by calling the PBAP_Un_Register_SDP_Record()
* function.
* \note A MACRO is provided to Delete the Service Record from the
* SDP Data Base. This MACRO maps the
* PBAP_Un_Register_SDP_Record() to the
* SDP_Delete_Service_Record() function.
* \note The Service Name is always added at Attribute ID 0x0100.
* A Language Base Attribute ID List is created that
* specifies that 0x0100 is UTF-8 Encoded, English Language.
*/
BTPSAPI_DECLARATION int BTPSAPI PBAP_Register_Server_SDP_Record(unsigned int BluetoothStackID, unsigned int PBAPID, char *ServiceName, DWord_t *SDPServiceRecordHandle);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_PBAP_Register_Server_SDP_Record_t)(unsigned int BluetoothStackID, unsigned int PBAPID, char *ServiceName, DWord_t *SDPServiceRecordHandle);
#endif
/*! @brief The following function adds a PBAP Client (PCE) Service Record to
* the SDP Database. @param BluetoothStackID The first parameter is the Bluetooth Stack ID
* of the stack on which to register this SDP record. @param ServiceName The second parameter is a pointer to ASCII, NULL terminated string containing
* the Service Name to include within the SDP Record. @param SDPServiceRecordHandle The final parameter is a pointer to a DWord_t which receives the SDP Service
* Record Handle if this function successfully creates an SDP Service
* Record. @return If this function returns zero, then the
* SDPServiceRecordHandle entry will contain the Service Record
* Handle of the added SDP Service Record. If this function fails, a
* negative return error code will be returned (see BTERRORS.H) and
* the SDPServiceRecordHandle value will be undefined.
* \note The Service Record Handle that is returned from this
* function will remain in the SDP Record Database until it
* is deleted by calling the PBAP_Un_Register_SDP_Record()
* function.
* \note A MACRO is provided to Delete the Service Record from the
* SDP Data Base. This MACRO maps the
* PBAP_Un_Register_SDP_Record() to the
* SDP_Delete_Service_Record() function.
* \note The Service Name is always added at Attribute ID 0x0100.
* A Language Base Attribute ID List is created that
* specifies that 0x0100 is UTF-8 Encoded, English Language.
*/
BTPSAPI_DECLARATION int BTPSAPI PBAP_Register_Client_SDP_Record(unsigned int BluetoothStackID, char *ServiceName, DWord_t *SDPServiceRecordHandle);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_PBAP_Register_Client_SDP_Record_t)(unsigned int BluetoothStackID, char *ServiceName, DWord_t *SDPServiceRecordHandle);
#endif
/*! The following MACRO is a utility MACRO that deletes the PBAP
* Profile Server SDP Service Record (specified by the third parameter) from the SDP Database. This MACRO maps to the
* SDP_Delete_Service_Record() function. This MACRO is only provided
* so that the caller doesn't have to sift through the SDP API for
* very simplistic applications. This function accepts as input the
* Bluetooth Stack ID of the Bluetooth Protocol Stack that the
* Service Record exists on, the PBAP ID (returned from a successful
* call to the PBAP_Open_Server_Port() function), and the SDP Service
* Record Handle. The SDP Service Record Handle was returned via a
* successful call to the PBAP_Register_Server_SDP_Record() function.
* See the PBAP_Register_Server_SDP_Record() function for more
* information. This MACRO returns the result of the
* SDP_Delete_Service_Record() function, which is zero for success or
* a negative return error code (see BTERRORS.H). If using this
* function to remove a Client SDP record, simply set PBAPID to zero.
*/
#define PBAP_Un_Register_SDP_Record(__BluetoothStackID, __PBAPID, __SDPRecordHandle) \
(SDP_Delete_Service_Record(__BluetoothStackID, __SDPRecordHandle))
/*! @brief The following function is responsible for opening a connection to
* a remote PBAP Server. @param BluetoothStackID The first parameter is the Bluetooth Stack
* ID of the local Bluetooth stack. @param BD_ADDR The second parameter is the
* remote Bluetooth Device Address of the Bluetooth PBAP Profile
* Server with which to connect. @param ServerPort The third parameter specifies the
* remote server port with which to connect. @param EventCallback The fourth parameter
* specifies the PBAP Profile Event Callback Function. @param CallbackParameter The final parameter is
* the Callback associated with this PBAP Profile Client.
* \note The ServerPort parameter MUST be between
* PBAP_PORT_NUMBER_MINIMUM and PBAP_PORT_NUMBER_MAXIMUM.
* @return This function returns a positive, non zero, value if successful or a
* negative return error code if an error occurs. A successful
* return code will be a PBAP ID that can be used to reference the
* remote opened PBAP Profile Server in ALL other PBAP Profile Client
* functions in this module. Once a remote server is opened, it can
* only be closed via a call to the PBAP_Close_Connection() function
* (passing the return value from this function).
*/
BTPSAPI_DECLARATION int BTPSAPI PBAP_Open_Remote_Server_Port(unsigned int BluetoothStackID, BD_ADDR_t BD_ADDR, unsigned int ServerPort, PBAP_Event_Callback_t EventCallback, unsigned long CallbackParameter);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_PBAP_Open_Remote_Server_Port_t)(unsigned int BluetoothStackID, BD_ADDR_t BD_ADDR, unsigned int ServerPort, PBAP_Event_Callback_t EventCallback, unsigned long CallbackParameter);
#endif
/*! @brief The following function is provided to allow a means to respond to
* a request to connect to the local PBAP Profile Server. @param BluetoothStackID
* The first parameter is the Bluetooth Stack ID of the Bluetooth Stack on
* which this server resides. @param PBAPID The second parameter is the PBAP ID
* that was returned from a previous PBAP_Open_Server_Port() function
* for this server. @param AcceptConnection The final parameter to this function is a
* Boolean_t that indicates whether to accept the pending connection.
* @return This function returns zero if successful, or a negative return
* value if there was an error.
* \note The connection to the server is not established until a
* etPBAP_Open_Port_Indication event has occurred.
*/
BTPSAPI_DECLARATION int BTPSAPI PBAP_Open_Request_Response(unsigned int BluetoothStackID, unsigned int PBAPID, Boolean_t AcceptConnection);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_PBAP_Open_Request_Response_t)(unsigned int BluetoothStackID, unsigned int PBAPID, Boolean_t AcceptConnection);
#endif
/*! @brief The following function is responsible for closing a currently
* ongoing PBAP Profile connection. @param BluetoothStackID The first parameter is the
* Bluetooth Stack ID of the Bluetooth Protocol Stack Instance that
* is associated with the PBAP Profile connection being closed.
* @param PBAPID The second parameter to this function is the PBAP ID of the PBAP
* Profile connection to be closed. @return This function returns zero if
* successful, or a negative return value if there was an error.
* \note If this function is called with a Server PBAP ID (a value
* returned from a call to PBAP_Open_Server_Port()) any
* clients currently connected to this server will be
* terminated, but the server will remained open and
* registered. If this function is called using a Client
* PBAP ID (a value returned from a call to
* PBAP_Open_Remote_Server_Port()), the client connection
* will be terminated/closed entirely.
*/
BTPSAPI_DECLARATION int BTPSAPI PBAP_Close_Connection(unsigned int BluetoothStackID, unsigned int PBAPID);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_PBAP_Close_Connection_t)(unsigned int BluetoothStackID, unsigned int PBAPID);
#endif
/*! @brief The following function is responsible for sending an Disconnect
* Request to the remote device/entity. @param BluetoothStackID The first parameter to this
* function is the Bluetooth Stack ID of the Bluetooth Protocol Stack
* Instance that is associated with the PBAP Profile connection being
* disconnected. @param PBAPID The second parameter to this function is the PBAP
* ID of the PBAP Profile connection to be disconnected (that was
* returned by a call to PBAP_Open_Remote_Server_Port()).
* @return This function returns zero if successful, or a negative return value if
* there was an error.
* \note Use of this function is optional and is provided for full
* compliance with some OBEX applications. Calling the
* PBAP_Close_Connection() function will achieve the same
* results without sending the OBEX disconnect packet
* beforehand. If is also possible to call this function
* and then immediately call PBAP_Close_Connection() without
* waiting for a confirmation because a Disconnect Request
* cannot be failed. Calling this function by itself and
* waiting for a response will cause the underlying
* connection to automatically be closed once the response
* is received. This will generate a Close Port Indication.
*/
BTPSAPI_DECLARATION int BTPSAPI PBAP_Disconnect_Request(unsigned int BluetoothStackID, unsigned int PBAPID);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_PBAP_Disconnect_Request_t)(unsigned int BluetoothStackID, unsigned int PBAPID);
#endif
/*! @brief The following function is responsible for Aborting ANY currently
* outstanding PBAP Profile Client Request. @param BluetoothStackID The first parameter is
* the Bluetooth Stack ID of the Bluetooth Stack for which the PBAP
* Profile Client is valid. @param PBAPID The second parameter to this function
* specifies the PBAP ID (returned from a successful call to the
* PBAP_Open_Remote_Server_Port() function). @return This function returns
* zero if successful, or a negative return error code if there was
* an error.
* \note There can only be one outstanding PBAP Profile Request
* active at any one time. Because of this, another PBAP
* Profile Request cannot be issued until either the current
* request is Aborted (by calling the PBAP_Abort_Request()
* function) or the current Request is completed (this is
* signified by receiving a Confirmation Event in the PBAP
* Profile Event Callback that was registered when the PBAP
* Profile Port was opened).
* \note Because of transmission latencies, it may be possible
* that a PBAP Profile Client Request that is to be aborted
* may have completed before the server was able to Abort
* the request. In either case, the caller will be notified
* via PBAP Profile Callback of the status of the previous
* Request.
*/
BTPSAPI_DECLARATION int BTPSAPI PBAP_Abort_Request(unsigned int BluetoothStackID, unsigned int PBAPID);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_PBAP_Abort_Request_t)(unsigned int BluetoothStackID, unsigned int PBAPID);
#endif
/*! @brief The following function generates a PBAP Pull Phonebook Request to
* the specified remote PBAP Server. @param BluetoothStackID The first parameter
* the ID of the Bluetooth Stack that is associated with this PBAP
* Client. @param PBAPID The second parameter specifies the PBAP ID for the local
* PBAP Client (returned from a successful call to the
* PBAP_Connect_Remote_Server_Port() function). @param ObjectName The third
* parameter contains the Name/Path of the Phonebook being requested
* by this Pull Phonebook operation. @param FilterLow The fourth parameter
* contains the lower 32 bits of the 64-bit filter attribute. @param
* FilterHigh The fifth parameter contains the higher 32 bits of the 64-bit
* filter attribute. @param Format The sixth parameter is an enumeration which
* specifies the vCard format requested in this Pull Phonebook
* request. If pfDefault is specified then the format will not be
* included in the request (note that the server will default to
* pfvCard21 in this case). @param MaxListCount The seventh parameter is an
* unsigned integer that specifies the maximum number of entries the
* client can handle. A value of 65535 means that the number of
* entries is not restricted. A MaxListCount of ZERO (0) indicates
* that this is a request for the number of used indexes in the
* Phonebook specified by the ObjectName parameter. @param
* ListStartOffset The final parameter specifies the index requested by the
* Client in this PullPhonebookRequest. @return This function returns zero
* if successful or a negative return error code if there was an
* error.
* \note A successful return code does not mean that the remote
* PBAP Profile Server successfully processed the command.
* The caller needs to check the confirmation result to
* determine if the remote PBAP Profile Server successfully
* executed the Request.
* \note There can only be one outstanding PBAP Profile Request
* active at any one time. Because of this, another PBAP
* Profile Request cannot be issued until either the current
* request is Aborted (by calling the PBAP_Abort_Request()
* function) or the current Request is completed (this is
* signified by receiving a Confirmation Event in the PBAP
* Profile Event Callback that was registered when the PBAP
* Profile Port was opened).
*/
BTPSAPI_DECLARATION int BTPSAPI PBAP_Pull_Phonebook_Request(unsigned int BluetoothStackID, unsigned int PBAPID, char *ObjectName, DWord_t FilterLow, DWord_t FilterHigh, PBAP_Format_t Format, Word_t MaxListCount, Word_t ListStartOffset);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_PBAP_Pull_Phonebook_Request_t)(unsigned int BluetoothStackID, unsigned int PBAPID, char *ObjectName, DWord_t FilterLow, DWord_t FilterHigh, PBAP_Format_t Format, Word_t MaxListCount, Word_t ListStartOffset);
#endif
/*! @brief The following function sends a PBAP Pull Phonebook Response to the
* specified remote PBAP Client. This is used for responding to a
* PBAP Pull Phonebook Indication. @param BluetoothStackID The
* ID of the Bluetooth Stack that is associated with this PBAP
* Server. @param PBAPID The PBAP ID of the PBAP
* Server responding to the request. @param ResponseCode
* The OBEX response code to include in the response. @param
* PhonebookSize Pointer to a variable that can
* optionally contain a Phonebook Size value to return in this
* request. This should be done if the received indication indicated
* a request for PhonebookSize by indicating a MaxListCount = ZERO
* (0). If this value is to be included in the response the Buffer
* parameter should be set to NULL and the BufferSize to ZERO. If
* this value is NOT to be used in the response, this parameter
* should be set to NULL. @param NewMissedCalls Pointer
* to a variable that can optionally contain the number of new missed
* calls which have not been checked on this server. This should
* only be included on requests for the 'mch' phonebook type. If
* this value is to be included in the response the Buffer parameter
* should be set to NULL and the BufferSize to ZERO. If this value
* is NOT to be used in the response, this parameter should be set to
* NULL. @param BufferSize The size in bytes of the data
* included in the specified Buffer. @param Buffer
* Pointer to a byte buffer containing the Phonebook data to be
* included in this response packet. @param AmountWritten
* Pointer to variable which will be written with the actual amount
* of data that was able to be included in the packet.
* @return This function returns zero if successful or a negative return error code if
* there was an error.
* \note Including a Buffer pointer and setting BufferSize > 0
* will cause a Body or End-of-Body header to be added to
* the packet, either on the first or subsequent packets.
* If the stack cannot include all the requested object data
* (BufferSize) in the current packet, a Body header will be
* used and AmountWritten will reflect that not all data was
* sent. If all data is included an End-of-Body header will
* be used.
* \note If AmountWritten returns an amount smaller than the
* specified BufferSize, not all the data was able to be
* sent. This function should be called again with an
* adjusted BufferSize and Buffer pointer to account for the
* data that was successfully sent.
*/
BTPSAPI_DECLARATION int BTPSAPI PBAP_Pull_Phonebook_Response(unsigned int BluetoothStackID, unsigned int PBAPID, Byte_t ResponseCode, Word_t *PhonebookSize, Byte_t *NewMissedCalls, unsigned int BufferSize, Byte_t *Buffer, unsigned int *AmountWritten);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_PBAP_Pull_Phonebook_Response_t)(unsigned int BluetoothStackID, unsigned int PBAPID, Byte_t ResponseCode, Word_t *PhonebookSize, Byte_t *NewMissedCalls, unsigned int BufferSize, Byte_t *Buffer, unsigned int *AmountWritten);
#endif
/*! @brief The following function generates a PBAP Set Phonebook Request to
* the specified remote PBAP Server. @param BluetoothStackID
* The ID of the Bluetooth Stack that is associated with this PBAP
* Client. @param PBAPID Specifies the PBAP ID for the local
* PBAP Client (returned from a successful call to the
* PBAP_Connect_Remote_Server_Port() function). @param PathOption
* An enumerated value that indicates the type of
* path change to request. @param ObjectName The
* folder name to include with this Set Phonebook request. This
* value can be NULL if no name is required for the selected
* PathOption. See the PBAP specification for more information.
* @return This function returns zero if successful or a negative return
* error code if there was an error.
* \note A successful return code does not mean that the remote
* PBAP Profile Server successfully processed the command.
* The caller needs to check the confirmation result to
* determine if the remote PBAP Profile Server successfully
* executed the Request.
* \note There can only be one outstanding PBAP Profile Request
* active at any one time. Because of this, another PBAP
* Profile Request cannot be issued until either the current
* request is Aborted (by calling the PBAP_Abort_Request()
* function) or the current Request is completed (this is
* signified by receiving a Confirmation Event in the PBAP
* Profile Event Callback that was registered when the PBAP
* Profile Port was opened).
*/
BTPSAPI_DECLARATION int BTPSAPI PBAP_Set_Phonebook_Request(unsigned int BluetoothStackID, unsigned int PBAPID, PBAP_Set_Path_Option_t PathOption, char *ObjectName);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_PBAP_Set_Phonebook_Request_t)(unsigned int BluetoothStackID, unsigned int PBAPID, PBAP_Set_Path_Option_t PathOption, char *ObjectName);
#endif
/*! @brief The following function sends a PBAP Set Phonebook Response to the
* specified remote PBAP Client. This is used for responding to a
* PBAP Set Phonebook Indication. @param BluetoothStackID
* The ID of the Bluetooth Stack that is associated with this PBAP
* Server. @param PBAPID Specifies the PBAP ID of the PBAP
* Server responding to the request. @param ResponseCode
* The OBEX response code to include in the response.
* @return This function returns zero if successful or a negative return error code if
* there was an error.
*/
BTPSAPI_DECLARATION int BTPSAPI PBAP_Set_Phonebook_Response(unsigned int BluetoothStackID, unsigned int PBAPID, Byte_t ResponseCode);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_PBAP_Set_Phonebook_Response_t)(unsigned int BluetoothStackID, unsigned int PBAPID, Byte_t ResponseCode);
#endif
/*! @brief The following function generates a PBAP Pull vCard Listing Request
* to the specified remote PBAP Server. @param BluetoothStackID
* The ID of the Bluetooth Stack that is associated with
* this PBAP Client. @param PBAPID Specifies the PBAP ID for
* the local PBAP Client (returned from a successful call to the
* PBAP_Connect_Remote_Server_Port() function). @param ObjectName
* Contains the folder of the Phonebook being requested by
* this Pull vCard Listing operation. This value can be NULL if a
* PhonebookSize request is being performed. @param ListOrder
* An enumerated type that determines the optionally requested
* order of the listing. Using the 'loDefault' value for this
* parameter will prevent this field from being added to the request
* (note that the server will default to loIndexed in this case).
* @param SearchAttribute An enumerated type that determines the
* optionally requested attribute used to filter this request. Using
* the 'saDefault' value for this parameter will prevent this
* field from being added to the request (note that the server will
* default to saIndexed in this case). @param SearchValue
* Contains an optional ASCII, Null-terminated character string that
* contains the string requested for search/filter. If this
* parameter is NULL, this field will be excluded from the request.
* @param MaxListCount An unsigned integer that specifies
* the maximum number of list entries the client can handle. A value
* of 65535 means that the number of entries is not restricted. A
* MaxListCount of ZERO (0) indicates that this is a request for the
* number of used indexes in the Phonebook specified by the
* ObjectName parameter. @param ListStartOffset Specifies the
* index requested by the Client in this Pull vCard Listing.
* @return This function returns zero if successful or a negative return error
* code if there was an error.
* \note A successful return code does not mean that the remote
* PBAP Profile Server successfully processed the command.
* The caller needs to check the confirmation result to
* determine if the remote PBAP Profile Server successfully
* executed the Request.
* \note There can only be one outstanding PBAP Profile Request
* active at any one time. Because of this, another PBAP
* Profile Request cannot be issued until either the current
* request is Aborted (by calling the PBAP_Abort_Request()
* function) or the current Request is completed (this is
* signified by receiving a Confirmation Event in the PBAP
* Profile Event Callback that was registered when the PBAP
* Profile Port was opened).
*/
BTPSAPI_DECLARATION int BTPSAPI PBAP_Pull_vCard_Listing_Request(unsigned int BluetoothStackID, unsigned int PBAPID, char *ObjectName, PBAP_List_Order_t ListOrder, PBAP_Search_Attribute_t SearchAttribute, char *SearchValue, Word_t MaxListCount, Word_t ListStartOffset);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_PBAP_Pull_vCard_Listing_Request_t)(unsigned int BluetoothStackID, unsigned int PBAPID, char *ObjectName, PBAP_List_Order_t ListOrder, PBAP_Search_Attribute_t SearchAttribute, char *SearchValue, Word_t MaxListCount, Word_t ListStartOffset);
#endif
/*! @brief The following function sends a PBAP Pull vCard Listing Response to
* the specified remote PBAP Client. This is used for responding to
* a PBAP Pull vCard Listing Indication. @param BluetoothStackID
* The ID of the Bluetooth Stack that is associated with
* this PBAP Server. @param PBAPID Specifies the PBAP ID of
* the PBAP Server responding to the request. @param ResponseCode
* parameter is the OBEX response code to include in the response.
* @param PhonebookSize A pointer to a variable that can
* optionally contain a Phonebook Size value to return in this
* request. This should be done if the received indication indicated
* a request for PhonebookSize by indicating a MaxListCount = ZERO
* (0). If this value is to be included in the response the Buffer
* parameter should be set to NULL and the BufferSize to ZERO. If
* this value is NOT to be used in the response, this parameter
* should be set to NULL. @param NewMissedCalls A pointer
* to a variable that can optionally contain the number of new missed
* calls which have not been checked on this server. This should
* only be included on requests for the 'mch' phonebook type. If
* this value is to be included in the response the Buffer parameter
* should be set to NULL and the BufferSize to ZERO. If this value
* is NOT to be used in the response, this parameter should be set to
* NULL. @param BufferSize The size in bytes of the data
* included in the specified Buffer. @param Buffer A
* pointer to a byte buffer containing the Phonebook listing data to
* be included in this response packet. @param AmountWritten
* A pointer to variable which will be written with the actual
* amount of data that was able to be included in the packet.
* @return This function returns zero if successful or a negative return error
* code if there was an error.
* \note Including a Buffer pointer and setting BufferSize > 0
* will cause a Body or End-of-Body header to be added to
* the packet, either on the first or subsequent packets.
* If the stack cannot include all the requested object data
* (BufferSize) in the current packet, a Body header will be
* used and AmountWritten will reflect that not all data was
* sent. If all data is included an End-of-Body header will
* be used.
* \note If AmountWritten returns an amount smaller than the
* specified BufferSize, not all the data was able to be
* sent. This function should be called again with an
* adjusted BufferSize and Buffer pointer to account for the
* data that was successfully sent.
*/
BTPSAPI_DECLARATION int BTPSAPI PBAP_Pull_vCard_Listing_Response(unsigned int BluetoothStackID, unsigned int PBAPID, Byte_t ResponseCode, Word_t *PhonebookSize, Byte_t *NewMissedCalls, unsigned int BufferSize, Byte_t *Buffer, unsigned int *AmountWritten);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_PBAP_Pull_vCard_Listing_Response_t)(unsigned int BluetoothStackID, unsigned int PBAPID, Byte_t ResponseCode, Word_t *PhonebookSize, Byte_t *NewMissedCalls, unsigned int BufferSize, Byte_t *Buffer, unsigned int *AmountWritten);
#endif
/*! @brief The following function generates a PBAP Pull vCard Entry Request
* to the specified remote PBAP Server. @param BluetoothStackID
* The ID of the Bluetooth Stack that is associated with
* this PBAP Client. @param PBAPID Specifies the PBAP ID for
* the local PBAP Client (returned from a successful call to the
* PBAP_Connect_Remote_Server_Port() function). @param ObjectName
* Contains the name of the Phonebook entry being requested
* by this Pull vCard Entry operation. @param FilterLow
* Contains the lower 32 bits of the 64-bit filter attribute. @param
* FilterHigh Contains the higher 32 bits of the 64-bit
* filter attribute. @param Format An enumeration which
* specifies the vCard format requested in this Pull vCard Entry
* request. If pfDefault is specified then the format will not be
* included in the request (note that in this case the server will
* default to pfvCard21 in this case). @return This function returns zero if
* successful or a negative return error code if there was an error.
* \note A successful return code does not mean that the remote
* PBAP Profile Server successfully processed the command.
* The caller needs to check the confirmation result to
* determine if the remote PBAP Profile Server successfully
* executed the Request.
* \note There can only be one outstanding PBAP Profile Request
* active at any one time. Because of this, another PBAP
* Profile Request cannot be issued until either the current
* request is Aborted (by calling the PBAP_Abort_Request()
* function) or the current Request is completed (this is
* signified by receiving a Confirmation Event in the PBAP
* Profile Event Callback that was registered when the PBAP
* Profile Port was opened).
*/
BTPSAPI_DECLARATION int BTPSAPI PBAP_Pull_vCard_Entry_Request(unsigned int BluetoothStackID, unsigned int PBAPID, char *ObjectName, DWord_t FilterLow, DWord_t FilterHigh, PBAP_Format_t Format);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_PBAP_Pull_vCard_Entry_Request_t)(unsigned int BluetoothStackID, unsigned int PBAPID, char *ObjectName, DWord_t FilterLow, DWord_t FilterHigh, PBAP_Format_t Format);
#endif
/*! @brief The following function sends a PBAP Pull vCard Entry Response to
* the specified remote PBAP Client. This is used for responding to
* a PBAP Pull vCard Entry Indication. @param BluetoothStackID
* The ID of the Bluetooth Stack that is associated with
* this PBAP Server. @param PBAPID Specifies the PBAP ID of
* the PBAP Server responding to the request. @param ResponseCode
* The OBEX response code to include in the response.
* @param BufferSize The size in bytes of the data included
* in the specified Buffer. @param Buffer A pointer to a
* byte buffer containing the Phonebook entry data to be included in
* this response packet. @param AmountWritten Apointer to
* variable which will be written with the actual amount of data that
* was able to be included in the packet. @return This function returns zero
* if successful or a negative return error code if there was an
* error.
* \note Including a Buffer pointer and setting BufferSize > 0
* will cause a Body or End-of-Body header to be added to
* the packet, either on the first or subsequent packets.
* If the stack cannot include all the requested object data
* (BufferSize) in the current packet, a Body header will be
* used and AmountWritten will reflect that not all data was
* sent. If all data is included an End-of-Body header will
* be used.
* \note If AmountWritten returns an amount smaller than the
* specified BufferSize, not all the data was able to be
* sent. This function should be called again with an
* adjusted BufferSize and Buffer pointer to account for the
* data that was successfully sent.
*/
BTPSAPI_DECLARATION int BTPSAPI PBAP_Pull_vCard_Entry_Response(unsigned int BluetoothStackID, unsigned int PBAPID, Byte_t ResponseCode, unsigned int BufferSize, Byte_t *Buffer, unsigned int *AmountWritten);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_PBAP_Pull_vCard_Entry_Response_t)(unsigned int BluetoothStackID, unsigned int PBAPID, Byte_t ResponseCode, unsigned int BufferSize, Byte_t *Buffer, unsigned int *AmountWritten);
#endif
/*! @brief The following function is responsible for providing a mechanism to
* query the current PBAP Profile Server Mode. @param BluetoothStackID The first parameter
* is the Bluetooth Stack ID of the Bluetooth Stack of the local PBAP
* Profile Server. @param PBAPID The second parameter is the PBAP ID that was
* returned from the PBAP_Open_Server_Port() function.
* @param ServerModeMask The final parameter is a pointer to a variable which will receive the
* current Server Mode Mask. @return This function returns zero if
* successful, or a negative return value if there was an error.
*/
BTPSAPI_DECLARATION int BTPSAPI PBAP_Get_Server_Mode(unsigned int BluetoothStackID, unsigned int PBAPID, unsigned long *ServerModeMask);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_PBAP_Get_Server_Mode_t)(unsigned int BluetoothStackID, unsigned int PBAPID, unsigned long *ServerModeMask);
#endif
/*! @brief The following function is responsible for providing a mechanism to
* change the current PBAP Profile Server Mode. @param BluetoothStackID The first parameter
* is the Bluetooth Stack ID of the Bluetooth Stack of the local PBAP
* Profile Server. @param PBAPID The second parameter is the PBAP ID that was
* returned from the PBAP_Open_Server_Port() function.
* @param ServerModeMask The final parameter is the new Server Mode Mask to use.
* @return This function returns zero if successful, or a negative return value if there
* was an error.
*/
BTPSAPI_DECLARATION int BTPSAPI PBAP_Set_Server_Mode(unsigned int BluetoothStackID, unsigned int PBAPID, unsigned long ServerModeMask);
#ifdef INCLUDE_BLUETOOTH_API_PROTOTYPES
typedef int (BTPSAPI *PFN_PBAP_Set_Server_Mode_t)(unsigned int BluetoothStackID, unsigned int PBAPID, unsigned long ServerModeMask);
#endif
#endif
Reference in New Issue View Git Blame Copy Permalink