FileDocCategorySizeDatePackage
BluetoothPbapClient.javaAPI DocAndroid 5.1 API33322Thu Mar 12 22:22:50 GMT 2015android.bluetooth.client.pbap

BluetoothPbapClient

public class BluetoothPbapClient extends Object
Public API to control Phone Book Profile (PCE role only).

This class defines methods that shall be used by application for the retrieval of phone book objects from remote device.

How to connect to remote device which is acting in PSE role:

  • Create a BluetoothDevice object which corresponds to remote device in PSE role;
  • Create an instance of BluetoothPbapClient class, passing BluetothDevice object along with a Handler to it;
  • Use {@link #setPhoneBookFolderRoot}, {@link #setPhoneBookFolderUp} and {@link #setPhoneBookFolderDown} to navigate in virtual phone book folder structure
  • Use {@link #pullPhoneBookSize} or {@link #pullVcardListingSize} to retrieve the size of selected phone book
  • Use {@link #pullPhoneBook} to retrieve phone book entries
  • Use {@link #pullVcardListing} to retrieve list of entries in the phone book
  • Use {@link #pullVcardEntry} to pull single entry from the phone book
Upon completion of each call above PCE will notify application if operation completed successfully (along with results) or failed.

Therefore, application should handle following events in its message queue handler:

  • EVENT_PULL_PHONE_BOOK_SIZE_DONE
  • EVENT_PULL_VCARD_LISTING_SIZE_DONE
  • EVENT_PULL_PHONE_BOOK_DONE
  • EVENT_PULL_VCARD_LISTING_DONE
  • EVENT_PULL_VCARD_ENTRY_DONE
  • EVENT_SET_PHONE_BOOK_DONE
and
  • EVENT_PULL_PHONE_BOOK_SIZE_ERROR
  • EVENT_PULL_VCARD_LISTING_SIZE_ERROR
  • EVENT_PULL_PHONE_BOOK_ERROR
  • EVENT_PULL_VCARD_LISTING_ERROR
  • EVENT_PULL_VCARD_ENTRY_ERROR
  • EVENT_SET_PHONE_BOOK_ERROR
connect and disconnect methods are introduced for testing purposes. An application does not need to use them as the session connection and disconnection happens automatically internally.

Fields Summary
private static final String
TAG
public static final String
ICH_PATH
Path to local incoming calls history object
public static final String
OCH_PATH
Path to local outgoing calls history object
public static final String
MCH_PATH
Path to local missed calls history object
public static final String
CCH_PATH
Path to local combined calls history object
public static final String
PB_PATH
Path to local main phone book object
public static final String
SIM_ICH_PATH
Path to incoming calls history object stored on the phone's SIM card
public static final String
SIM_OCH_PATH
Path to outgoing calls history object stored on the phone's SIM card
public static final String
SIM_MCH_PATH
Path to missed calls history object stored on the phone's SIM card
public static final String
SIM_CCH_PATH
Path to combined calls history object stored on the phone's SIM card
public static final String
SIM_PB_PATH
Path to main phone book object stored on the phone's SIM card
public static final byte
ORDER_BY_DEFAULT
Indicates to server that default sorting order shall be used for vCard listing.
public static final byte
ORDER_BY_INDEXED
Indicates to server that indexed sorting order shall be used for vCard listing.
public static final byte
ORDER_BY_ALPHABETICAL
Indicates to server that alphabetical sorting order shall be used for the vCard listing.
public static final byte
ORDER_BY_PHONETIC
Indicates to server that phonetical (based on sound attribute) sorting order shall be used for the vCard listing.
public static final byte
SEARCH_ATTR_NAME
Indicates to server that Name attribute of vCard shall be used to carry out the search operation on
public static final byte
SEARCH_ATTR_NUMBER
Indicates to server that Number attribute of vCard shall be used to carry out the search operation on
public static final byte
SEARCH_ATTR_SOUND
Indicates to server that Sound attribute of vCard shall be used to carry out the search operation
public static final byte
VCARD_TYPE_21
VCard format version 2.1
public static final byte
VCARD_TYPE_30
VCard format version 3.0
public static final long
VCARD_ATTR_VERSION
public static final long
VCARD_ATTR_FN
public static final long
VCARD_ATTR_N
public static final long
VCARD_ATTR_PHOTO
public static final long
VCARD_ATTR_BDAY
public static final long
VCARD_ATTR_ADDR
public static final long
VCARD_ATTR_LABEL
public static final long
VCARD_ATTR_TEL
public static final long
VCARD_ATTR_EMAIL
public static final long
VCARD_ATTR_MAILER
public static final long
VCARD_ATTR_TZ
public static final long
VCARD_ATTR_GEO
public static final long
VCARD_ATTR_TITLE
public static final long
VCARD_ATTR_ROLE
public static final long
VCARD_ATTR_LOGO
public static final long
VCARD_ATTR_AGENT
public static final long
VCARD_ATTR_ORG
public static final long
VCARD_ATTR_NOTE
public static final long
VCARD_ATTR_REV
public static final long
VCARD_ATTR_SOUND
public static final long
VCARD_ATTR_URL
public static final long
VCARD_ATTR_UID
public static final long
VCARD_ATTR_KEY
public static final long
VCARD_ATTR_NICKNAME
public static final long
VCARD_ATTR_CATEGORIES
public static final long
VCARD_ATTR_PROID
public static final long
VCARD_ATTR_CLASS
public static final long
VCARD_ATTR_SORT_STRING
public static final long
VCARD_ATTR_X_IRMC_CALL_DATETIME
public static final short
MAX_LIST_COUNT
Maximal number of entries of the phone book that PCE can handle
public static final int
EVENT_SET_PHONE_BOOK_DONE
Event propagated upon completion of setPhoneBookFolderRoot, setPhoneBookFolderUp or setPhoneBookFolderDown request.

This event indicates that request completed successfully.

public static final int
EVENT_PULL_PHONE_BOOK_DONE
Event propagated upon completion of pullPhoneBook request.

This event carry on results of the request.

The resulting message contains:
msg.arg1 newMissedCalls parameter (only in case of missed calls history object request)
msg.obj which is a list of VCardEntry objects

public static final int
EVENT_PULL_VCARD_LISTING_DONE
Event propagated upon completion of pullVcardListing request.

This event carry on results of the request.

The resulting message contains:
msg.arg1 newMissedCalls parameter (only in case of missed calls history object request)
msg.obj which is a list of BluetoothPbapCard objects

public static final int
EVENT_PULL_VCARD_ENTRY_DONE
Event propagated upon completion of pullVcardEntry request.

This event carry on results of the request.

The resulting message contains:
msg.obj vCard as and object of type VCardEntry

public static final int
EVENT_PULL_PHONE_BOOK_SIZE_DONE
Event propagated upon completion of pullPhoneBookSize request.

This event carry on results of the request.

The resulting message contains:
msg.arg1 size of the phone book

public static final int
EVENT_PULL_VCARD_LISTING_SIZE_DONE
Event propagated upon completion of pullVcardListingSize request.

This event carry on results of the request.

The resulting message contains:
msg.arg1 size of the phone book listing

public static final int
EVENT_SET_PHONE_BOOK_ERROR
Event propagated upon completion of setPhoneBookFolderRoot, setPhoneBookFolderUp or setPhoneBookFolderDown request. This event indicates an error during operation.
public static final int
EVENT_PULL_PHONE_BOOK_ERROR
Event propagated upon completion of pullPhoneBook request. This event indicates an error during operation.
public static final int
EVENT_PULL_VCARD_LISTING_ERROR
Event propagated upon completion of pullVcardListing request. This event indicates an error during operation.
public static final int
EVENT_PULL_VCARD_ENTRY_ERROR
Event propagated upon completion of pullVcardEntry request. This event indicates an error during operation.
public static final int
EVENT_PULL_PHONE_BOOK_SIZE_ERROR
Event propagated upon completion of pullPhoneBookSize request. This event indicates an error during operation.
public static final int
EVENT_PULL_VCARD_LISTING_SIZE_ERROR
Event propagated upon completion of pullVcardListingSize request. This event indicates an error during operation.
public static final int
EVENT_SESSION_CONNECTED
Event propagated when PCE has been connected to PSE
public static final int
EVENT_SESSION_DISCONNECTED
Event propagated when PCE has been disconnected from PSE
public static final int
EVENT_SESSION_AUTH_REQUESTED
public static final int
EVENT_SESSION_AUTH_TIMEOUT
private final android.os.Handler
mClientHandler
private final BluetoothPbapSession
mSession
private ConnectionState
mConnectionState
private SessionHandler
mSessionHandler
Constructors Summary
public BluetoothPbapClient(android.bluetooth.BluetoothDevice device, android.os.Handler handler)
Constructs PCE object

param
device BluetoothDevice that corresponds to remote acting in PSE role
param
handler the handle that will be used by PCE to notify events and results to application
throws
NullPointerException

        if (device == null) {
            throw new NullPointerException("BluetothDevice is null");
        }

        mClientHandler = handler;

        mSessionHandler = new SessionHandler(this);

        mSession = new BluetoothPbapSession(device, mSessionHandler);
Methods Summary
public voidabort()
Aborts current request, if any

        mSession.abort();
public voidconnect()
Starts a pbap session. This method set up rfcomm session, obex session and waits for requests to be transfered to PSE.

        mSession.start();
public voiddisconnect()
Stops all the active transactions and disconnects from the server.

        mSession.stop();
public voidfinalize()

        if (mSession != null) {
            mSession.stop();
        }
public android.bluetooth.client.pbap.BluetoothPbapClient$ConnectionStategetState()

        return mConnectionState;
public booleanpullPhoneBook(java.lang.String pbName)
Pulls complete phone book. This method pulls phone book which entries are of VCARD_TYPE_21 type and each single vCard contains minimal required set of fields and the number of entries in response is not limited.

param
pbName absolute path to the phone book
return
true if request has been sent successfully; false otherwise; upon completion PCE sends {@link #EVENT_PULL_PHONE_BOOK_DONE} or {@link #EVENT_PULL_PHONE_BOOK_ERROR} in case of failure

        return pullPhoneBook(pbName, 0, VCARD_TYPE_21, 0, 0);
public booleanpullPhoneBook(java.lang.String pbName, long filter, byte format)
Pulls complete phone book. This method pulls all entries from the phone book.

param
pbName absolute path to the phone book
param
filter bit mask which indicates which fields of the vCard shall be included in each entry of the resulting list
param
format vCard format of entries in the resulting list
return
true if request has been sent successfully; false otherwise; upon completion PCE sends {@link #EVENT_PULL_PHONE_BOOK_DONE} or {@link #EVENT_PULL_PHONE_BOOK_ERROR} in case of failure

        return pullPhoneBook(pbName, filter, format, 0, 0);
public booleanpullPhoneBook(java.lang.String pbName, int maxListCount, int listStartOffset)
Pulls complete phone book. This method pulls entries from the phone book limited to the number of maxListCount starting from the position of listStartOffset.

The resulting list contains vCard objects in version VCARD_TYPE_21 which in turns contain minimal required set of vCard fields.

param
pbName absolute path to the phone book
param
maxListCount limits number of entries in the response
param
listStartOffset offset to the first entry of the list that would be returned
return
true if request has been sent successfully; false otherwise; upon completion PCE sends {@link #EVENT_PULL_PHONE_BOOK_DONE} or {@link #EVENT_PULL_PHONE_BOOK_ERROR} in case of failure

        return pullPhoneBook(pbName, 0, VCARD_TYPE_21, maxListCount, listStartOffset);
public booleanpullPhoneBook(java.lang.String pbName, long filter, byte format, int maxListCount, int listStartOffset)
Pulls complete phone book.

param
pbName absolute path to the phone book
param
filter bit mask which indicates which fields of the vCard hall be included in each entry of the resulting list
param
format vCard format of entries in the resulting list
param
maxListCount limits number of entries in the response
param
listStartOffset offset to the first entry of the list that would be returned
return
true if request has been sent successfully; false otherwise; upon completion PCE sends {@link #EVENT_PULL_PHONE_BOOK_DONE} or {@link #EVENT_PULL_PHONE_BOOK_ERROR} in case of failure

        BluetoothPbapRequest req = new BluetoothPbapRequestPullPhoneBook(pbName, filter, format,
                maxListCount, listStartOffset);
        return mSession.makeRequest(req);
public booleanpullPhoneBookSize(java.lang.String pbName)
Requests for the number of entries in the phone book.

param
pbName absolute path to the phone book
return
true if request has been sent successfully; false otherwise; upon completion PCE sends {@link #EVENT_PULL_PHONE_BOOK_SIZE_DONE} or {@link #EVENT_PULL_PHONE_BOOK_SIZE_ERROR} in case of failure

        BluetoothPbapRequestPullPhoneBookSize req = new BluetoothPbapRequestPullPhoneBookSize(
                pbName);

        return mSession.makeRequest(req);
public booleanpullVcardEntry(java.lang.String handle)
Pulls single vCard object

param
handle handle to the vCard which shall be pulled
return
true if request has been sent successfully; false otherwise; upon completion PCE sends {@link #EVENT_PULL_VCARD_DONE} or
link
#EVENT_PULL_VCARD_ERROR} in case of failure

        return pullVcardEntry(handle, (byte) 0, VCARD_TYPE_21);
public booleanpullVcardEntry(java.lang.String handle, long filter, byte format)
Pulls single vCard object

param
handle handle to the vCard which shall be pulled
param
filter bit mask of the vCard fields that shall be included in the resulting vCard
param
format resulting vCard version
return
true if request has been sent successfully; false otherwise; upon completion PCE sends {@link #EVENT_PULL_VCARD_DONE}
link
#EVENT_PULL_VCARD_ERROR} in case of failure

        BluetoothPbapRequest req = new BluetoothPbapRequestPullVcardEntry(handle, filter, format);
        return mSession.makeRequest(req);
public booleanpullVcardListing(java.lang.String folder)
Pulls list of entries in the phone book.

This method pulls the list of entries in the folder.

param
folder the name of the folder to be retrieved
return
true if request has been sent successfully; false otherwise; upon completion PCE sends {@link #EVENT_PULL_VCARD_LISTING_DONE} or {@link #EVENT_PULL_VCARD_LISTING_ERROR} in case of failure

        return pullVcardListing(folder, ORDER_BY_DEFAULT, SEARCH_ATTR_NAME, null, 0, 0);
public booleanpullVcardListing(java.lang.String folder, byte order)
Pulls list of entries in the folder.

param
folder the name of the folder to be retrieved
param
order the sorting order of the resulting list of entries
return
true if request has been sent successfully; false otherwise; upon completion PCE sends {@link #EVENT_PULL_VCARD_LISTING_DONE} or {@link #EVENT_PULL_VCARD_LISTING_ERROR} in case of failure

        return pullVcardListing(folder, order, SEARCH_ATTR_NAME, null, 0, 0);
public booleanpullVcardListing(java.lang.String folder, byte searchAttr, java.lang.String searchVal)
Pulls list of entries in the folder. Only entries where searchAttr attribute of vCard matches searchVal will be listed.

param
folder the name of the folder to be retrieved
param
searchAttr vCard attribute which shall be used to carry out search operation on
param
searchVal text string used by matching routine to match the value of the attribute indicated by SearchAttr
return
true if request has been sent successfully; false otherwise; upon completion PCE sends {@link #EVENT_PULL_VCARD_LISTING_DONE} or {@link #EVENT_PULL_VCARD_LISTING_ERROR} in case of failure

        return pullVcardListing(folder, ORDER_BY_DEFAULT, searchAttr, searchVal, 0, 0);
public booleanpullVcardListing(java.lang.String folder, byte order, int maxListCount, int listStartOffset)
Pulls list of entries in the folder.

param
folder the name of the folder to be retrieved
param
order the sorting order of the resulting list of entries
param
maxListCount limits number of entries in the response
param
listStartOffset offset to the first entry of the list that would be returned
return
true if request has been sent successfully; false otherwise; upon completion PCE sends {@link #EVENT_PULL_VCARD_LISTING_DONE} or {@link #EVENT_PULL_VCARD_LISTING_ERROR} in case of failure

        return pullVcardListing(folder, order, SEARCH_ATTR_NAME, null, maxListCount,
                listStartOffset);
public booleanpullVcardListing(java.lang.String folder, int maxListCount, int listStartOffset)
Pulls list of entries in the folder.

param
folder the name of the folder to be retrieved
param
maxListCount limits number of entries in the response
param
listStartOffset offset to the first entry of the list that would be returned
return
true if request has been sent successfully; false otherwise; upon completion PCE sends {@link #EVENT_PULL_VCARD_LISTING_DONE} or {@link #EVENT_PULL_VCARD_LISTING_ERROR} in case of failure

        return pullVcardListing(folder, ORDER_BY_DEFAULT, SEARCH_ATTR_NAME, null, maxListCount,
                listStartOffset);
public booleanpullVcardListing(java.lang.String folder, byte order, byte searchAttr, java.lang.String searchVal, int maxListCount, int listStartOffset)
Pulls list of entries in the folder.

param
folder the name of the folder to be retrieved
param
order the sorting order of the resulting list of entries
param
searchAttr vCard attribute which shall be used to carry out search operation on
param
searchVal text string used by matching routine to match the value of the attribute indicated by SearchAttr
param
maxListCount limits number of entries in the response
param
listStartOffset offset to the first entry of the list that would be returned
return
true if request has been sent successfully; false otherwise; upon completion PCE sends {@link #EVENT_PULL_VCARD_LISTING_DONE} or {@link #EVENT_PULL_VCARD_LISTING_ERROR} in case of failure

        BluetoothPbapRequest req = new BluetoothPbapRequestPullVcardListing(folder, order,
                searchAttr, searchVal, maxListCount, listStartOffset);
        return mSession.makeRequest(req);
public booleanpullVcardListingSize(java.lang.String folder)
Requests for the number of entries in the phone book listing.

param
folder the name of the folder to be retrieved
return
true if request has been sent successfully; false otherwise; upon completion PCE sends {@link #EVENT_PULL_VCARD_LISTING_SIZE_DONE} or {@link #EVENT_PULL_VCARD_LISTING_SIZE_ERROR} in case of failure

        BluetoothPbapRequestPullVcardListingSize req = new BluetoothPbapRequestPullVcardListingSize(
                folder);

        return mSession.makeRequest(req);
private voidsendToClient(int eventId)

        sendToClient(eventId, 0, null);
private voidsendToClient(int eventId, int param)

        sendToClient(eventId, param, null);
private voidsendToClient(int eventId, java.lang.Object param)

        sendToClient(eventId, 0, param);
private voidsendToClient(int eventId, int param1, java.lang.Object param2)

        mClientHandler.obtainMessage(eventId, param1, 0, param2).sendToTarget();
public booleansetAuthResponse(java.lang.String key)

        Log.d(TAG, " setAuthResponse key=" + key);
        return mSession.setAuthResponse(key);
public booleansetPhoneBookFolderDown(java.lang.String folder)
Sets current folder to selected sub-folder

param
folder the name of the sub-folder
return
@return true if request has been sent successfully; false otherwise; upon completion PCE sends {@link #EVENT_SET_PHONE_BOOK_DONE} or {@link #EVENT_SET_PHONE_BOOK_ERROR} in case of failure

        BluetoothPbapRequest req = new BluetoothPbapRequestSetPath(folder);
        return mSession.makeRequest(req);
public booleansetPhoneBookFolderRoot()
Sets current folder to root

return
true if request has been sent successfully; false otherwise; upon completion PCE sends {@link #EVENT_SET_PHONE_BOOK_DONE} or {@link #EVENT_SET_PHONE_BOOK_ERROR} in case of failure

        BluetoothPbapRequest req = new BluetoothPbapRequestSetPath(false);
        return mSession.makeRequest(req);
public booleansetPhoneBookFolderUp()
Sets current folder to parent

return
true if request has been sent successfully; false otherwise; upon completion PCE sends {@link #EVENT_SET_PHONE_BOOK_DONE} or {@link #EVENT_SET_PHONE_BOOK_ERROR} in case of failure

        BluetoothPbapRequest req = new BluetoothPbapRequestSetPath(true);
        return mSession.makeRequest(req);