doc: Add profile API documentation

Makefile.am

@@ -380,7 +380,7 @@ CLEANFILES += $(rules_DATA)
 EXTRA_DIST += scripts/bluetooth-hid2hci.rules scripts/bluetooth-serial.rules
 
 EXTRA_DIST += doc/manager-api.txt \
-		doc/adapter-api.txt doc/device-api.txt \
+		doc/adapter-api.txt doc/device-api.txt doc/profile-api.txt \
 		doc/service-api.txt doc/agent-api.txt doc/attribute-api.txt \
 		doc/network-api.txt doc/input-api.txt doc/audio-api.txt \
 		doc/control-api.txt doc/hfp-api.txt doc/health-api.txt \

doc/bluez-docs.xml

@@ -68,6 +68,13 @@
     </para>
   </reference>
 
+  <reference id="profile">
+    <title>Profile interface</title>
+    <para>
+<programlisting><xi:include href="profile-api.txt" parse="text" /></programlisting>
+    </para>
+  </reference>
+
   <reference id="agent">
     <title>Agent interface</title>
     <para>

doc/device-api.txt

@@ -83,6 +83,29 @@ Methods		dict GetProperties()
 
 			Possible errors: org.bluez.Error.NotConnected
 
+		void ConnectProfile(string uuid)
+
+			This method connects a specific profile of this
+			device. The profile needs to be registered client
+			profile.
+
+			Possible errors: org.bluez.Error.DoesNotExist
+					 org.bluez.Error.AlreadyConnected
+					 org.bluez.Error.ConnectFailed
+
+		void DisconnectProfile(string uuid)
+
+			This method disconnects a specific profile of
+			this device. The profile needs to be registered
+			client profile.
+
+			There is no connection tracking for a profile, so
+			as long as the profile is registered this will always
+			succeed.
+
+			Possible errors: org.bluez.Error.DoesNotExist
+					 org.bluez.Error.NotConnected
+
 Signals		PropertyChanged(string name, variant value)
 
 			This signal indicates a changed value of the given

doc/manager-api.txt

@@ -37,6 +37,83 @@ Methods		dict GetProperties()
 			Possible errors: org.bluez.Error.InvalidArguments
 					 org.bluez.Error.NoSuchAdapter
 
+		void RegisterProfile(object profile, string uuid, dict options)
+
+			This registers a profile implementation.
+
+			If an application disconnects from the bus all
+			its registered profiles will be removed.
+
+			HFP HS UUID: 0000111e-0000-1000-8000-00805f9b34fb
+
+				Default RFCOMM channel is 6. And this requires
+				authentication.
+
+			Available options:
+
+				string Name
+
+					Human readable name for the profile
+
+				string Role
+
+					For asymmetric profiles that do not
+					have UUIDs available to uniquely
+					identify each side this
+					parameter allows specifying the
+					precise local role.
+
+					Possible values: "client", "server"
+
+				uint16 Channel
+
+					RFCOMM channel number that is used
+					for client and server UUIDs.
+
+					If applicable it will be used in the
+					SDP record as well.
+
+				uint16 PSM
+
+					PSM number that is used for client
+					and server UUIDs.
+
+					If applicable it will be used in the
+					SDP record as well.
+
+				boolean RequireAuthentication
+
+					Pairing is required before connections
+					will be established. No devices will
+					be connected if not paired.
+
+				boolean RequireAuthorization
+
+					Request authorization before any
+					connection will be established.
+
+				boolean AutoConnect
+
+					In case of a client UUID this will
+					force connection of the RFCOMM or
+					L2CAP channels when a remote device
+					is connected.
+
+				string ServiceRecord
+
+					Provide a manual SDP record.
+
+			Possible errors: org.bluez.Error.InvalidArguments
+			                 org.bluez.Error.AlreadyExists
+
+		void UnregisterProfile(object profile)
+
+			This unregisters the profile that has been previously
+			registered. The object path parameter must match the
+			same value that has been used on registration.
+
+			Possible errors: org.bluez.Error.DoesNotExist
+
 Signals		PropertyChanged(string name, variant value)
 
 			This signal indicates a changed value of the given

doc/profile-api.txt

@@ -0,0 +1,53 @@
+BlueZ D-Bus Profile API description
+***********************************
+
+Copyright (C) 2012  Intel Corporation. All rights reserved.
+
+
+Profile hierarchy
+=================
+
+Service		unique name
+Interface	org.bluez.Profile
+Object path	freely definable
+
+Methods		void Release()
+
+			This method gets called when the service daemon
+			unregisters the profile. A profile can use it to do
+			cleanup tasks. There is no need to unregister the
+			profile, because when this method gets called it has
+			already been unregistered.
+
+		void NewConnection(object device, fd)
+
+			This method gets called when a new service level
+			connection has been made and authorized.
+
+			Possible errors: org.bluez.Error.Rejected
+			                 org.bluez.Error.Canceled
+
+		void RequestDisconnection(object device)
+
+			This method gets called when a profile gets
+			disconnected.
+
+			The file descriptor is no longer owned by the service
+			daemon and the profile implementation needs to take
+			care of cleaning up all connections.
+
+			If multiple file descriptors are indicated via
+			NewConnection, it is expected that all of them
+			are disconnected before returning from this
+			method call.
+
+			Possible errors: org.bluez.Error.Rejected
+			                 org.bluez.Error.Canceled
+
+		void Cancel()
+
+			This method gets called to indicate that the profile
+			request failed before a reply was returned.
+
+			All request are queued and there will be only one
+			pending pequest at a time per profile.