From 535f90da9b207e6dc90e19b275050199c0b8c6da Mon Sep 17 00:00:00 2001 From: Marcel Holtmann Date: Mon, 10 Dec 2012 23:03:24 +0100 Subject: [PATCH] doc: Add API documentation from obexd repository --- doc/obex-agent-api.txt | 31 ++ doc/obex-client-api.txt | 667 ++++++++++++++++++++++++++++++++++++++++ doc/obexd-api.txt | 87 ++++++ 3 files changed, 785 insertions(+) create mode 100644 doc/obex-agent-api.txt create mode 100644 doc/obex-client-api.txt create mode 100644 doc/obexd-api.txt diff --git a/doc/obex-agent-api.txt b/doc/obex-agent-api.txt new file mode 100644 index 000000000..20181a60d --- /dev/null +++ b/doc/obex-agent-api.txt @@ -0,0 +1,31 @@ +obexd Agent API description +********************************** + +Copyright (C) 2007-2010 Nokia Corporation +Copyright (C) 2007-2010 Marcel Holtmann + + +Agent hierarchy +=============== + +Service unique name +Interface org.bluez.obex.Agent +Object path freely definable + +Methods + string Authorize(object transfer, string bt_address, string name, + string type, int32 length, int32 time) + + This method gets called when the service daemon + needs to accept/reject a Bluetooth object push request. + Returns the full path (including the filename) where + the object shall be stored. + + Possible errors: org.bluez.obex.Error.Rejected + org.bluez.obex.Error.Canceled + + void Cancel() + + This method gets called to indicate that the agent + request failed before a reply was returned. It cancels + the previous request. diff --git a/doc/obex-client-api.txt b/doc/obex-client-api.txt new file mode 100644 index 000000000..19c85415c --- /dev/null +++ b/doc/obex-client-api.txt @@ -0,0 +1,667 @@ +OBEX client API description +*************************** + +Copyright (C) 2007-2010 Marcel Holtmann +Copyright (C) 2011-2012 BMW Car IT GmbH. All rights reserved. + + +Client hierarchy +================ + +Service org.bluez.obex.client +Interface org.bluez.obex.Client +Object path / + +Methods object CreateSession(string destination, dict args) + + Create a new OBEX session for the given remote address. + + The last parameter is a dictionary to hold optional or + type-specific parameters. Typical parameters that can + be set in this dictionary include the following: + + string "Target" : type of session to be created + string "Source" : local address to be used + byte "Channel" + + The currently supported targets are the following: + + "FTP" + "MAP" + "OPP" + "PBAP" + "SYNC" + + void RemoveSession(object session) + + Unregister session and abort pending transfers. + +Session hierarchy +================= + +Service org.bluez.obex.client +Interface org.bluez.obex.Session +Object path [variable prefix]/{session0,session1,...} + +Methods dict GetProperties() + + Returns all properties for the session. + + string GetCapabilities() + + Get remote device capabilities. + +Properties string Source [readonly] + + string Destination [readonly] + + byte Channel [readonly] + +Object Push hierarchy +===================== + +Service org.bluez.obex.client +Interface org.bluez.obex.ObjectPush +Object path [variable prefix]/{session0,session1,...} + +Methods object, dict SendFile(string sourcefile) + + Send one local file to the remote device. + + The returned path represents the newly created transfer, + which should be used to find out if the content has been + successfully transferred or if the operation fails. + + The properties of this transfer are also returned along + with the object path, to avoid a call to GetProperties. + + object, dict PullBusinessCard(string targetfile) + + Request the business card from a remote device and + store it in the local file. + + If an empty target file is given, a name will be + automatically calculated for the temporary file. + + The returned path represents the newly created transfer, + which should be used to find out if the content has been + successfully transferred or if the operation fails. + + The properties of this transfer are also returned along + with the object path, to avoid a call to GetProperties. + + object, dict ExchangeBusinessCards(string clientfile, + string targetfile) + + Push the client's business card to the remote device + and then retrieve the remote business card and store + it in a local file. + + If an empty target file is given, a name will be + automatically calculated for the temporary file. + + The returned path represents the newly created transfer, + which should be used to find out if the content has been + successfully transferred or if the operation fails. + + The properties of this transfer are also returned along + with the object path, to avoid a call to GetProperties. + +File Transfer hierarchy +======================= + +Service org.bluez.obex.client +Interface org.bluez.obex.FileTransfer +Object path [variable prefix]/{session0,session1,...} + +Methods void ChangeFolder(string folder) + + Change the current folder of the remote device. + + void CreateFolder(string folder) + + Create a new folder in the remote device. + + array{dict} ListFolder() + + Returns a dictionary containing information about + the current folder content. + + The following keys are defined: + + string Name : Object name in UTF-8 format + string Type : Either "folder" or "file" + uint64 Size : Object size or number of items in + folder + string Permission : Group, owner and other + permission + uint64 Modified : Last change + uint64 Accessed : Last access + uint64 Created : Creation date + + object, dict GetFile(string targetfile, string sourcefile) + + Copy the source file (from remote device) to the + target file (on local filesystem). + + If an empty target file is given, a name will be + automatically calculated for the temporary file. + + The returned path represents the newly created transfer, + which should be used to find out if the content has been + successfully transferred or if the operation fails. + + The properties of this transfer are also returned along + with the object path, to avoid a call to GetProperties. + + object, dict PutFile(string sourcefile, string targetfile) + + Copy the source file (from local filesystem) to the + target file (on remote device). + + The returned path represents the newly created transfer, + which should be used to find out if the content has been + successfully transferred or if the operation fails. + + The properties of this transfer are also returned along + with the object path, to avoid a call to GetProperties. + + void CopyFile(string sourcefile, string targetfile) + + Copy a file within the remote device from source file + to target file. + + void MoveFile(string sourcefile, string targetfile) + + Move a file within the remote device from source file + to the target file. + + void Delete(string file) + + Deletes the specified file/folder. + +Phonebook Access hierarchy +======================= + +Service org.bluez.obex.client +Interface org.bluez.obex.PhonebookAccess +Object path [variable prefix]/{session0,session1,...} + +Methods void Select(string location, string phonebook) + + Select the phonebook object for other operations. Should + be call before all the other operations. + + location : Where the phonebook is stored, possible + inputs : + "INT" ( "INTERNAL" which is default ) + "SIM" ( "SIM1" ) + "SIM2" + ... + + phonebook : Possible inputs : + "pb" : phonebook for the saved contacts + "ich": incoming call history + "och": outgoing call history + "mch": missing call history + "cch": combination of ich och mch + + object, dict PullAll(string targetfile, dict filters) + + Return the entire phonebook object from the PSE server + in plain string with vcard format, and store it in + a local file. + + If an empty target file is given, a name will be + automatically calculated for the temporary file. + + The returned path represents the newly created transfer, + which should be used to find out if the content has been + successfully transferred or if the operation fails. + + The properties of this transfer are also returned along + with the object path, to avoid a call to GetProperties. + + Possible filters: Format, Order, Offset, MaxCount and + Fields + + array{string vcard, string name} List(dict filters) + + Return an array of vcard-listing data where every entry + consists of a pair of strings containing the vcard + handle and the contact name. For example: + "1.vcf" : "John" + + Possible filters: Order, Offset and MaxCount + + + object, dict + Pull(string vcard, string targetfile, dict filters) + + Given a vcard handle, retrieve the vcard in the current + phonebook object and store it in a local file. + + If an empty target file is given, a name will be + automatically calculated for the temporary file. + + The returned path represents the newly created transfer, + which should be used to find out if the content has been + successfully transferred or if the operation fails. + + The properties of this transfer are also returned along + with the object path, to avoid a call to GetProperties. + + Possbile filters: Format and Fields + + + array{string vcard, string name} + Search(string field, string value, dict filters) + + Search for entries matching the given condition and + return an array of vcard-listing data where every entry + consists of a pair of strings containing the vcard + handle and the contact name. + + vcard : name paired string match the search condition. + + field : the field in the vcard to search with + { "name" (default) | "number" | "sound" } + value : the string value to search for + + + Possible filters: Order, Offset and MaxCount + + uint16 GetSize() + + Return the number of entries in the selected phonebook + object that are actually used (i.e. indexes that + correspond to non-NULL entries). + + array{string} ListFilterFields() + + Return All Available fields that can be used in Fields + filter. + +Filter: string Format: + + Items vcard format + + Possible values: "vcard21" (default) or "vcard30" + + string Order: + + Items order + + Possible values: "indexed" (default), "alphanumeric" or + "phonetic" + + uint16 Offset: + + Offset of the first item, default is 0 + + uint16 MaxCount: + + Maximum number of items, default is unlimited (65535) + + array{string} Fields: + + Item vcard fields, default is all values. + + Possible values can be query with ListFilterFields. + + +Synchronization hierarchy +======================= + +Service org.bluez.obex.client +Interface org.bluez.obex.Synchronization +Object path [variable prefix]/{session0,session1,...} + +Methods void SetLocation(string location) + + Set the phonebook object store location for other + operations. Should be called before all the other + operations. + + location: Where the phonebook is stored, possible + values: + "INT" ( "INTERNAL" which is default ) + "SIM1" + "SIM2" + ...... + + object, dict GetPhonebook(string targetfile) + + Retrieve an entire Phonebook Object store from remote + device, and stores it in a local file. + + If an empty target file is given, a name will be + automatically calculated for the temporary file. + + The returned path represents the newly created transfer, + which should be used to find out if the content has been + successfully transferred or if the operation fails. + + The properties of this transfer are also returned along + with the object path, to avoid a call to GetProperties. + + object, dict PutPhonebook(string sourcefile) + + Send an entire Phonebook Object store to remote device. + + The returned path represents the newly created transfer, + which should be used to find out if the content has been + successfully transferred or if the operation fails. + + The properties of this transfer are also returned along + with the object path, to avoid a call to GetProperties. + +Message Access hierarchy +========================= + +Service org.bluez.obex.client +Interface org.bluez.obex.MessageAccess +Object path [variable prefix]/{session0,session1,...} + +Methods void SetFolder(string name) + + Set working directory for current session, *name* may + be the directory name or '..[/dir]'. + + array{dict} ListFolders(dict filter) + + Returns a dictionary containing information about + the current folder content. + + The following keys are defined: + + string Name : Folder name + + Possible filters: Offset and MaxCount + + array{string} ListFilterFields() + + Return all available fields that can be used in Fields + filter. + + array{object, dict} ListMessages(string folder, dict filter) + + Returns an array containing the messages found in the + given folder. + + Possible Filters: Offset, MaxCount, Fields, Type, + PeriodStart, PeriodEnd, Status, Recipient, Sender, + Priority + + Each message is represented by an object path followed + by a dictionary of the properties. + + Properties: + + string Subject: + + Message subject + + string Timestamp: + + Message timestamp + + string Sender: + + Message sender name + + string SenderAddress: + + Message sender address + + string ReplyTo: + + Message Reply-To address + + string Recipient: + + Message recipient name + + string RecipientAddress: + + Message recipient address + + string Type: + + Message type + + Possible values: "EMAIL", "SMS_GSM", + "SMS_CDMA" and "MMS" + + uint64 Size: + + Message size in bytes + + string Status: + + Message reception status + + Possible values: "complete", + "fractioned" and "notification" + + boolean Priority: + + Message priority flag + + boolean Read: + + Message read flag + + boolean Sent: + + Message sent flag + + boolean Protected: + + Message protected flag + + void UpdateInbox(void) + + Request remote to update its inbox. + + +Filter: uint16 Offset: + + Offset of the first item, default is 0 + + uint16 MaxCount: + + Maximum number of items, default is 1024 + + array{string} Fields: + + Message fields, default is all values. + + Possible values can be query with ListFilterFields. + + array{string} Types: + + Filter messages by type. + + Possible values: "sms", "email", "mms". + + string PeriodBegin: + + Filter messages by starting period. + + Possible values: Date in "YYYYMMDDTHHMMSS" format. + + string PeriodEnd: + + Filter messages by ending period. + + Possible values: Date in "YYYYMMDDTHHMMSS" format. + + boolean Read: + + Filter messages by read flag. + + Possible values: True for read or False for unread + + string Recipient: + + Filter messages by recipient address. + + string Sender: + + Filter messages by sender address. + + gboolean Priority: + + Filter messages by priority flag. + + Possible values: True for high priority or False for + non-high priority + +Message hierarchy +================= + +Service org.bluez.obex.client +Interface org.bluez.obex.Message +Object path [variable prefix]/{session0,session1,...}/{message0,...} + +Methods object, dict Get(string targetfile, boolean attachment) + + Download message and store it in the target file. + + If an empty target file is given, a temporary file + will be automatically generated. + + The returned path represents the newly created transfer, + which should be used to find out if the content has been + successfully transferred or if the operation fails. + + The properties of this transfer are also returned along + with the object path, to avoid a call to GetProperties. + + dict GetProperties() + + Returns all properties for the message. See the + properties section for available properties. + + void SetProperty (string name, variant value) + + Sets value to the mentioned property. + + Possible properties: Read and Deleted. + + +Properties string Subject [readonly] + + Message subject + + string Timestamp [readonly] + + Message timestamp + + string Sender [readonly] + + Message sender name + + string SenderAddress [readonly] + + Message sender address + + string ReplyTo [readonly] + + Message Reply-To address + + string Recipient [readonly] + + Message recipient name + + string RecipientAddress [readonly] + + Message recipient address + + string Type [readonly] + + Message type + + Possible values: "EMAIL", "SMS_GSM", + "SMS_CDMA" and "MMS" + + uint64 Size [readonly] + + Message size in bytes + + string Status [readonly] + + Message reception status + + Possible values: "complete", + "fractioned" and "notification" + + boolean Priority [readonly] + + Message priority flag + + boolean Read [read/write] + + Message read flag + + boolean Deleted [writeonly] + + Message read flag + + boolean Sent [readonly] + + Message sent flag + + boolean Protected [readonly] + + Message protected flag + + +Transfer hierarchy +================== + +Service org.bluez.obex.client +Interface org.bluez.obex.Transfer +Object path [variable prefix]/{session0,session1,...}/{transfer0,...} + +Methods dict GetProperties() + + Returns all properties for the transfer. See the + properties section for available properties. + + void Cancel() + + Cancels this transfer. + +Properties string Name [readonly] + + Name of the transferred object. + + uint64 Size [readonly] + + Size of the transferred object. If the size is + unknown, then this property will not be present. + + string Filename [readonly, optional] + + Complete name of the file being received or sent. + + uint64 Progress [readonly, optional] + + Number of bytes transferred. For queued transfers, this + value will not be present. + +Signals PropertyChanged(string name, variant value) + + This signal indicates a changed value of the given + property. + + void Complete() + + Informs that the transfer has completed successfully. + + void Error(string code, string message) + + Informs that the transfer has been terminated because + of some error. diff --git a/doc/obexd-api.txt b/doc/obexd-api.txt new file mode 100644 index 000000000..3244479f8 --- /dev/null +++ b/doc/obexd-api.txt @@ -0,0 +1,87 @@ +obexd API description +********************************** + +Copyright (C) 2007-2010 Nokia Corporation +Copyright (C) 2007-2010 Marcel Holtmann + + +Manager hierarchy +=============== + +Service org.bluez.obex +Interface org.bluez.obex.Manager +Object path / + +Methods + void RegisterAgent(object agent) + + Register an agent to request authorization of + the user to accept/reject objects. Object push + service needs to authorize each received object. + + Possible errors: org.bluez.obex.Error.AlreadyExists + + void UnregisterAgent(object agent) + + This unregisters the agent that has been previously + registered. The object path parameter must match the + same value that has been used on registration. + + Possible errors: org.bluez.obex.Error.DoesNotExist + +Signals SessionCreated(object session) + + Signal sent when OBEX connection has been accepted. + (FTP only) + + SessionRemoved(object session) + + Sent when the transport is disconnected + (FTP only) + + TransferStarted(object transfer) + + Signal sent when an object push operation starts. + (OPP only) + + TransferCompleted(object transfer, boolean success) + + Signal sent when the object has been received + or an error happens. + (OPP only) + + +Transfer hierarchy +=============== + +Service org.bluez.obex +Interface org.bluez.obex.Transfer +Object path /transfer{0, 1, 2, ...} + +Methods + void Cancel() + + Stops the current transference. + +Signals + Progress(int32 total, int32 transfered) + + +Session hierarchy +=============== + +Service org.bluez.obex +Interface org.bluez.obex.Session +Object path /session{0, 1, 2, ...} + +Methods + dict GetProperties() + + +Signals TBD + + +Properties + string Address [readonly] + + Bluetooth device address or USB -- 2.47.3