/* * 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 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: * * "[ ]", * * where is a string representing query name, and 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: * * "= = ... =" * * 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= [inp_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= channel= pix= framedims=\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 * 'x', 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 */