chromeos/dbus: Add BlueZ Media Endpoint Service Provider API.

chromeos/dbus/bluetooth_media_endpoint_service_provider.h

+// Copyright 2014 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef CHROMEOS_DBUS_BLUETOOTH_MEDIA_ENDPOINT_SERVICE_PROVIDER_H_
+#define CHROMEOS_DBUS_BLUETOOTH_MEDIA_ENDPOINT_SERVICE_PROVIDER_H_
+
+#include <vector>
+
+#include "base/callback.h"
+#include "chromeos/chromeos_export.h"
+#include "dbus/bus.h"
+#include "dbus/message.h"
+#include "dbus/object_path.h"
+
+namespace chromeos {
+
+// BluetoothMediaEndpointServiceProvider is used to provide a D-Bus object that
+// the bluetooth daemon can commuicate with to serve as media source/sink.

[Ben Chan, 2014/11/16 18:57:56]

bluetooth -> Bluetooth

as media -> as a media

[Miao, 2014/11/17 20:51:02]

Done.

+//
+// Instantiate with a chosen D-Bus object path and a delegate object, and pass
+// chromsthe D-Bus object path as |endpoint_path| argument to the

[Ben Chan, 2014/11/16 18:57:56]

chromsthe -> the

[Miao, 2014/11/17 20:51:02]

Done.

+// chromeos::BluetoothMediaClient::RegisterEndoint() method.
+//
+// After initiateing a connection between an audio source and an audio sink, the

[Ben Chan, 2014/11/16 18:57:56]

initiateing -> initiating

[Miao, 2014/11/17 20:51:02]

Done.

+// Bluetooth daemon will make calls to this endpoint object and they will be
+// passed to user's Delegate object for handling. Responses should be returned
+// using the callbacks supplied to this methods.

[Ben Chan, 2014/11/16 18:57:56]

this methods?  these methods or this method?  actually, which method(s)?

[Miao, 2014/11/17 20:51:02]

Done.

+class CHROMEOS_EXPORT BluetoothMediaEndpointServiceProvider {
+ public:
+  // Delegate is the interface for reacting to endpoint requests. User
+  // applications will implement this interface to handle either A2DP Sink or
+  // Source.
+  class Delegate {
+   public:
+    virtual ~Delegate() {}
+
+    // SelectConfigurationCallback is used for the SelectConfiguration() method,
+    // it should be called with two arguements, the |configuration| which is
+    // agreed by the application and the |length| of |configuration|.
+    typedef base::Callback<void(const uint8_t*, size_t)>
+        SelectConfigurationCallback;
+
+    // This method will be called after an Audio Source receives the agreed
+    // capabilities from the Audio Sink to set the configuration for the
+    // media transport object. |transport_path| is the path to the
+    // MediaTransport object, and |properties| are the properties for that
+    // MediaTransport object.
+    virtual void SetConfiguration(const dbus::ObjectPath& transport_path,
+                                  const dbus::MessageReader& properties) = 0;
+
+    // This method will be called when an Audio Source connects to an Audio Sink
+    // and asks it to decide the configuration to be used during the oncoming
+    // streaing. Audio Sources provide |capabilities| as a reference, where

[Ben Chan, 2014/11/16 18:57:56]

streaing -> streaming

[Miao, 2014/11/17 20:51:02]

Done.

+    // a user application can use this |capabilities| to figure out

[Ben Chan, 2014/11/16 18:57:56]

this |capabilities| -> these |capabilities| 

[Miao, 2014/11/17 20:51:02]

Done.

+    // a well-matched configuration and return it to the Audio Source via
+    // |callback|.
+    virtual void SelectConfiguration(
+        const uint8_t* capabilities,
+        size_t length,
+        const SelectConfigurationCallback& callback) = 0;
+
+    // This method will be called when an Audio Source disconnects to an Audio

[Ben Chan, 2014/11/16 18:57:56]

disconnects to -> disconnects from

[Miao, 2014/11/17 20:51:02]

Done.

+    // Sink. A user applications is supposed to clear any of its resources which

[Ben Chan, 2014/11/16 18:57:56]

applications -> application

[Miao, 2014/11/17 20:51:02]

Done.

+    // it keeps for that partiular connection. |transport_path| is the Media

[Ben Chan, 2014/11/16 18:57:56]

partiular -> particular

[Miao, 2014/11/17 20:51:02]

Done.

+    // Transport object which has been kept by an endpoint during the
+    // connection.
+    virtual void ClearConfiguration(const dbus::ObjectPath& transport_path) = 0;
+
+    // This method will be called when the Bluetooth daemon unregisters the
+    // Media Endpoint. Media Endpoint objects can use this method to clean up
+    // tasks. These is no need to unregister the endpoint, since when this

[Ben Chan, 2014/11/16 18:57:56]

These -> There

[Miao, 2014/11/17 20:51:02]

Done.

+    // method gets called, that endpoint has been unregistered.
+    virtual void Release() = 0;
+  };
+
+  virtual ~BluetoothMediaEndpointServiceProvider();
+
+  // Create the instance where |bus| is the D-Bus bus connection to export the

[Ben Chan, 2014/11/16 18:57:56]

Create -> Creates (for consistency with comments in other classes)

[Miao, 2014/11/17 20:51:02]

Done.

+  // object noto, |object_path| is the object path that it should have and

[Ben Chan, 2014/11/16 18:57:56]

noto?

[Miao, 2014/11/17 20:51:02]

Done.

+  // |delegate| is the object to which all method calls will be passed and
+  // responses generated from.
+  static BluetoothMediaEndpointServiceProvider* Create(
+      dbus::Bus* bus,
+      const dbus::ObjectPath& object_path,
+      Delegate* delegate);
+
+ protected:
+  BluetoothMediaEndpointServiceProvider();
+
+ private:
+  DISALLOW_COPY_AND_ASSIGN(BluetoothMediaEndpointServiceProvider);
+};
+
+}  // namespace chromeos
+
+#endif  // CHROMEOS_DBUS_BLUETOOTH_MEDIA_ENDPOINT_SERVICE_PROVIDER_H_