path: root/guest/hals/camera/QemuClient.h

/*
 * Copyright (C) 2011 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#ifndef HW_EMULATOR_CAMERA_QEMU_CLIENT_H
#define HW_EMULATOR_CAMERA_QEMU_CLIENT_H

/*
 * Contains declaration of classes that encapsulate connection to camera
 * services in the emulator via qemu pipe.
 */

#include <hardware/qemud.h>

namespace android {

/****************************************************************************
 * Qemu query
 ***************************************************************************/

/* Encapsulates a query to the emulator.
 * Guest exchanges data with the emulator via queries sent over the qemu pipe.
 * The queries as well as replies to the queries are all strings (except for the
 * 'frame' query where reply is a framebuffer).
 * Each query is formatted as such:
 *
 *      "<query name>[ <parameters>]",
 *
 * where <query name> is a string representing query name, and <parameters> are
 * optional parameters for the query. If parameters are present, they must be
 * separated from the query name with a single space, and they must be formatted
 * as such:
 *
 *      "<name1>=<value1> <name2>=<value2> ... <nameN>=<valueN>"
 *
 * I.e.:
 *  - Every parameter must have a name, and a value.
 *  - Name and value must be separated with '='.
 *  - No spaces are allowed around '=' separating name and value.
 *  - Parameters must be separated with a single space character.
 *  - No '=' character is allowed in name and in value.
 *
 * There are certain restrictions on strings used in the query:
 *  - Spaces are allowed only as separators.
 *  - '=' are allowed only to divide parameter names from parameter values.
 *
 * Emulator replies to each query in two chunks:
 * - 8 bytes encoding the payload size as a string containing hexadecimal
 *   representation of the payload size value. This is done in order to simplify
 *   dealing with different endianness on the host, and on the guest.
 * - Payload, whose size is defined by the first chunk.
 *
 * Every payload always begins with two characters, encoding the result of the
 * query:
 *  - 'ok' Encoding the success
 *  - 'ko' Encoding a failure.
 * After that payload may have optional data. If payload has more data following
 * the query result, there is a ':' character separating them. If payload
 * carries only the result, it always ends with a zero-terminator. So, payload
 * 'ok'/'ko' prefix is always 3 bytes long: it either includes a
 * zero-terminator, if there is no data, or a ':' separator.
 */
class QemuQuery {
 public:
  /* Constructs an uninitialized QemuQuery instance. */
  QemuQuery();

  /* Constructs and initializes QemuQuery instance for a query.
   * Param:
   *  query_string - Query string. This constructor can also be used to
   *      construct a query that doesn't have parameters. In this case query
   *      name can be passed as a parameter here.
   */
  explicit QemuQuery(const char* query_string);

  /* Constructs and initializes QemuQuery instance for a query with parameters.
   * Param:
   *  query_name - Query name.
   *  query_param - Query parameters. Can be NULL.
   */
  QemuQuery(const char* query_name, const char* query_param);

  /* Destructs QemuQuery instance. */
  ~QemuQuery();

  /****************************************************************************
   * Public API
   ***************************************************************************/

  /* Creates new query.
   * Note: this method will reset this instance prior to creating a new query
   * in order to discard possible "leftovers" from the previous query.
   * Param:
   *  query_name - Query name.
   *  query_param - Query parameters. Can be NULL.
   * Return:
   *  NO_ERROR on success, or an appropriate error status.
   */
  status_t createQuery(const char* name, const char* param);

  /* Completes the query after a reply from the emulator.
   * This method will parse the reply buffer, and calculate the final query
   * status, which depends not only on the transport success / failure, but
   * also on 'ok' / 'ko' in the reply buffer.
   * Param:
   *  status - Query delivery status. This status doesn't necessarily reflects
   *      the final query status (which is defined by 'ok'/'ko' prefix in the
   *      reply buffer). This status simply states whether or not the query has
   *      been sent, and a reply has been received successfuly. However, if
   *      this status indicates a failure, it means that the entire query has
   *      failed.
   * Return:
   *  NO_ERROR on success, or an appropriate error status on failure. Note that
   *  status returned here just signals whether or not the method has succeeded.
   *  Use isQuerySucceeded() / getCompletionStatus() methods of this class to
   *  check the final query status.
   */
  status_t completeQuery(status_t status);

  /* Resets the query from a previous use. */
  void resetQuery();

  /* Checks if query has succeeded.
   * Note that this method must be called after completeQuery() method of this
   * class has been executed.
   */
  inline bool isQuerySucceeded() const {
    return mQueryDeliveryStatus == NO_ERROR && mReplyStatus != 0;
  }

  /* Gets final completion status of the query.
   * Note that this method must be called after completeQuery() method of this
   * class has been executed.
   * Return:
   *  NO_ERROR if query has succeeded, or an appropriate error status on query
   *  failure.
   */
  inline status_t getCompletionStatus() const {
    if (mQueryDeliveryStatus == NO_ERROR) {
      if (mReplyStatus) {
        return NO_ERROR;
      } else {
        return EINVAL;
      }
    } else {
      return mQueryDeliveryStatus;
    }
  }

  /****************************************************************************
   * Public data memebers
   ***************************************************************************/

 public:
  /* Query string. */
  char* mQuery;
  /* Query delivery status. */
  status_t mQueryDeliveryStatus;
  /* Reply buffer */
  char* mReplyBuffer;
  /* Reply data (past 'ok'/'ko'). If NULL, there were no data in reply. */
  char* mReplyData;
  /* Reply buffer size. */
  size_t mReplySize;
  /* Reply data size. */
  size_t mReplyDataSize;
  /* Reply status: 1 - ok, 0 - ko. */
  int mReplyStatus;

  /****************************************************************************
   * Private data memebers
   ***************************************************************************/

 protected:
  /* Preallocated buffer for small queries. */
  char mQueryPrealloc[256];
};

/****************************************************************************
 * Qemu client base
 ***************************************************************************/

/* Encapsulates a connection to the 'camera' service in the emulator via qemu
 * pipe.
 */
class QemuClient {
 public:
  /* Constructs QemuClient instance. */
  QemuClient();

  /* Destructs QemuClient instance. */
  virtual ~QemuClient();

  /****************************************************************************
   * Qemu client API
   ***************************************************************************/

 public:
  /* Connects to the 'camera' service in the emulator via qemu pipe.
   * Param:
   *  param - Parameters to pass to the camera service. There are two types of
   *      camera services implemented by the emulator. The first one is a
   *      'camera factory' type of service that provides list of cameras
   *      connected to the host. Another one is an 'emulated camera' type of
   *      service that provides interface to a camera connected to the host. At
   *      the connection time emulator makes distinction between the two by
   *      looking at connection parameters: no parameters means connection to
   *      the 'factory' service, while connection with parameters means
   *      connection to an 'emulated camera' service, where camera is identified
   *      by one of the connection parameters. So, passing NULL, or an empty
   *      string to this method will establish a connection with the 'factory'
   *      service, while not empty string passed here will establish connection
   *      with an 'emulated camera' service. Parameters defining the emulated
   *      camera must be formatted as such:
   *
   *          "name=<device name> [inp_channel=<input channel #>]",
   *
   *      where 'device name' is a required parameter defining name of the
   *      camera device, and 'input channel' is an optional parameter (positive
   *      integer), defining the input channel to use on the camera device.
   *      Note that device name passed here must have been previously obtained
   *      from the factory service using 'list' query.
   * Return:
   *  NO_ERROR on success, or an appropriate error status.
   */
  virtual status_t connectClient(const char* param);

  /* Disconnects from the service. */
  virtual void disconnectClient();

  /* Sends data to the service.
   * Param:
   *  data, data_size - Data to send.
   * Return:
   *  NO_ERROR on success, or an appropriate error status on failure.
   */
  virtual status_t sendMessage(const void* data, size_t data_size);

  /* Receives data from the service.
   * This method assumes that data to receive will come in two chunks: 8
   * characters encoding the payload size in hexadecimal string, followed by
   * the paylod (if any).
   * This method will allocate data buffer where to receive the response.
   * Param:
   *  data - Upon success contains address of the allocated data buffer with
   *      the data received from the service. The caller is responsible for
   *      freeing allocated data buffer.
   *  data_size - Upon success contains size of the data received from the
   *      service.
   * Return:
   *  NO_ERROR on success, or an appropriate error status on failure.
   */
  virtual status_t receiveMessage(void** data, size_t* data_size);

  /* Sends a query, and receives a response from the service.
   * Param:
   *  query - Query to send to the service. When this method returns, the query
   *  is completed, and all its relevant data members are properly initialized.
   * Return:
   *  NO_ERROR on success, or an appropriate error status on failure. Note that
   *  status returned here is not the final query status. Use
   * isQuerySucceeded(), or getCompletionStatus() method on the query object to
   * see if it has succeeded. However, if this method returns a failure, it
   * means that the query has failed, and there is no guarantee that its data
   * members are properly initialized (except for the 'mQueryDeliveryStatus',
   * which is always in the proper state).
   */
  virtual status_t doQuery(QemuQuery* query);

  /****************************************************************************
   * Data members
   ***************************************************************************/

 protected:
  /* Qemu pipe handle. */
  int mPipeFD;

 private:
  /* Camera service name. */
  static const char mCameraServiceName[];
};

/****************************************************************************
 * Qemu client for the 'factory' service.
 ***************************************************************************/

/* Encapsulates QemuClient for the 'factory' service. */
class FactoryQemuClient : public QemuClient {
 public:
  /* Constructs FactoryQemuClient instance. */
  FactoryQemuClient();

  /* Destructs FactoryQemuClient instance. */
  ~FactoryQemuClient();

  /****************************************************************************
   * Public API
   ***************************************************************************/

 public:
  /* Lists camera devices connected to the host.
   * Param:
   *  list - Upon success contains a list of cameras connected to the host. The
   *      list returned here is represented as a string, containing multiple
   *      lines separated with '\n', where each line represents a camera. Each
   *      camera line is formatted as such:
   *
   *          "name=<device name> channel=<num> pix=<num>
   * framedims=<dimensions>\n"
   *
   *      Where:
   *      - 'name' is the name of the camera device attached to the host. This
   *        name must be used for subsequent connection to the 'emulated camera'
   *        service for that camera.
   *      - 'channel' - input channel number (positive int) to use to
   * communicate with the camera.
   *      - 'pix' - pixel format (a "fourcc" uint), chosen for the video frames
   *        by the camera service.
   *      - 'framedims' contains a list of frame dimensions supported by the
   *        camera for the chosen pixel format. Each etry in the list is in form
   *        '<width>x<height>', where 'width' and 'height' are numeric values
   *        for width and height of a supported frame dimension. Entries in
   *        this list are separated with ',' with no spaces between the entries.
   * Return:
   *  NO_ERROR on success, or an appropriate error status on failure.
   */
  status_t listCameras(char** list);

  /****************************************************************************
   * Names of the queries available for the emulated camera factory.
   ***************************************************************************/

 private:
  /* List cameras connected to the host. */
  static const char mQueryList[];
};

/****************************************************************************
 * Qemu client for an 'emulated camera' service.
 ***************************************************************************/

/* Encapsulates QemuClient for an 'emulated camera' service.
 */
class CameraQemuClient : public QemuClient {
 public:
  /* Constructs CameraQemuClient instance. */
  CameraQemuClient();

  /* Destructs CameraQemuClient instance. */
  ~CameraQemuClient();

  /****************************************************************************
   * Public API
   ***************************************************************************/

 public:
  /* Queries camera connection.
   * Return:
   *  NO_ERROR on success, or an appropriate error status on failure.
   */
  status_t queryConnect();

  /* Queries camera disconnection.
   * Return:
   *  NO_ERROR on success, or an appropriate error status on failure.
   */
  status_t queryDisconnect();

  /* Queries camera to start capturing video.
   * Param:
   *  pixel_format - Pixel format that is used by the client to push video
   *      frames to the camera framework.
   *  width, height - Frame dimensions, requested by the framework.
   * Return:
   *  NO_ERROR on success, or an appropriate error status on failure.
   */
  status_t queryStart(uint32_t pixel_format, int width, int height);

  /* Queries camera to stop capturing video.
   * Return:
   *  NO_ERROR on success, or an appropriate error status on failure.
   */
  status_t queryStop();

  /* Queries camera for the next video frame.
   * Param:
   *  vframe, vframe_size - Define buffer, allocated to receive a video frame.
   *      Any of these parameters can be 0, indicating that the caller is
   *      interested only in preview frame.
   *  pframe, pframe_size - Define buffer, allocated to receive a preview frame.
   *      Any of these parameters can be 0, indicating that the caller is
   *      interested only in video frame.
   *  r_scale, g_scale, b_scale - White balance scale.
   *  exposure_comp - Expsoure compensation.
   * Return:
   *  NO_ERROR on success, or an appropriate error status on failure.
   */
  status_t queryFrame(void* vframe, void* pframe, size_t vframe_size,
                      size_t pframe_size, float r_scale, float g_scale,
                      float b_scale, float exposure_comp);

  /****************************************************************************
   * Names of the queries available for the emulated camera.
   ***************************************************************************/

 private:
  /* Connect to the camera. */
  static const char mQueryConnect[];
  /* Disconnect from the camera. */
  static const char mQueryDisconnect[];
  /* Start video capturing. */
  static const char mQueryStart[];
  /* Stop video capturing. */
  static const char mQueryStop[];
  /* Query frame(s). */
  static const char mQueryFrame[];
};

}; /* namespace android */

#endif /* HW_EMULATOR_CAMERA_QEMU_CLIENT_H */