| /* ------------------------------------------------------------------ |
| * Copyright (C) 1998-2009 PacketVideo |
| * |
| * 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. |
| * ------------------------------------------------------------------- |
| */ |
| // -*- c++ -*- |
| // = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = |
| |
| // P V M I _ M I O _ C O N T R O L |
| |
| // = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = |
| |
| /*! \addtogroup pvmimiocontrol PvmiMioControl |
| * |
| * @{ |
| */ |
| |
| |
| /*! \file pvmi_mio_control.h |
| \brief This file contains the abstractions for media input-output control. |
| */ |
| |
| #ifndef PVMI_MIO_CONTROL_H_INCLUDED |
| #define PVMI_MIO_CONTROL_H_INCLUDED |
| |
| /* |
| This class defines an abstract interface for media input-output control |
| */ |
| #ifndef OSCL_BASE_H_INCLUDED |
| #include "oscl_base.h" |
| #endif |
| #ifndef OSCL_VECTOR_H_INCLUDED |
| #include "oscl_vector.h" |
| #endif |
| #ifndef PV_UUID_H_INCLUDED |
| #include "pv_uuid.h" |
| #endif |
| #ifndef PV_INTERFACE_H_INCLUDED |
| #include "pv_interface.h" |
| #endif |
| #ifndef PVMI_MEDIA_TRANSFER_H_INCLUDED |
| #include "pvmi_media_transfer.h" |
| #endif |
| #ifndef PVMI_MEDIA_IO_OBSERVER_H_INCLUDED |
| #include "pvmi_media_io_observer.h" |
| #endif |
| #ifndef PVMF_RETURN_CODES_H_INCLUDED |
| #include "pvmf_return_codes.h" |
| #endif |
| #ifndef PVMF_FORMAT_TYPES_H_INCLUDED |
| #include "pvmf_format_type.h" |
| #endif |
| #ifndef PVMI_KVP_H_INCLUDED |
| #include "pvmi_kvp.h" |
| #endif |
| |
| /** \class PvmiMIOControl |
| ** This class defines an abstract interface for media input-output control |
| */ |
| |
| class PvmiMIOControl |
| { |
| |
| public: |
| |
| virtual ~PvmiMIOControl() {} |
| |
| /** |
| * This method establishes a connection to the media I/O component. This is a prerequisite |
| * to any other interaction |
| * |
| * @param aSession This output parametre will be filled in with an opaque session ID |
| * which will be used to identify the connection session. |
| * @param aObserver Specifies an observer class to be registered |
| * for handling the results of asynchronous requests |
| * @returns PVMFSuccess if the operation is succesful. PVMFFailure otherwise. |
| */ |
| |
| virtual PVMFStatus connect(PvmiMIOSession& aSession, |
| PvmiMIOObserver* aObserver) = 0; |
| |
| |
| |
| /** |
| * Once all interaction with the media I/O component is complete, the session can be |
| * terminated with the disconnect call. Any pending asynchronous requests associated |
| * with that session will be cancelled and a cancel status will be returned for each |
| * them using the observer callback. |
| * |
| * @param aSession The opaque session ID which is used to identify the connection session. |
| * @returns PvmiSuccess if operation is succesful. PvmiFailure otherwise. |
| */ |
| |
| virtual PVMFStatus disconnect(PvmiMIOSession aSession) = 0; |
| |
| |
| /** |
| * The media I/O component provides a factory API to allocate and return a reference to PvmiMediaTransfer interface. |
| * The call succeeds only if the supplied parameters to the function are within the capabilities of the |
| * component as specified in the previous section. |
| * |
| * @param aSession The opaque session ID which is used to identify the connection session. |
| * @param read_formats list of formats that will be used for reading with this end point |
| * @param read_flags Specify the modes that will be used for reading. |
| * @param write_formats list of formats that will be used for writing this end point |
| * @param write_flags Specify the modes that will be used for reading. |
| * @returns If all the parameters are verified, a reference to a PvmiMediaTransfer |
| * interface shall be returned. |
| * @throw The function shall leave with PvmfErrNotSupported, |
| * if any of the parameters are outside the capabilities |
| * of the component. |
| */ |
| |
| virtual PvmiMediaTransfer* createMediaTransfer( |
| PvmiMIOSession& aSession, |
| PvmiKvp* read_formats = NULL, int32 read_flags = 0, |
| PvmiKvp* write_formats = NULL, int32 write_flags = 0) = 0; |
| |
| |
| |
| /** |
| * A media transfer session can be terminated by using this API |
| * |
| * @param aSession The opaque session ID which is used to identify the connection session. |
| * @param media_transfer list of formats that will be used for reading with this end point |
| * @returns A pre-requisite to deleting a PvmiMediaTransfer interface is |
| * that any outstanding read or write buffers must be returned |
| * to the interface. |
| * @throw The function shall leave with PvmfErrBusy if an attempt is made |
| * to delete it while there are outstanding buffers. |
| */ |
| |
| virtual void deleteMediaTransfer( |
| PvmiMIOSession& aSession, |
| PvmiMediaTransfer* media_transfer) = 0; |
| |
| |
| // Async requests that will trigger callback events |
| /** |
| * This API is to allow for extensibility of the PVMF Node interface. |
| * It allows a caller to ask for all UUIDs associated with a particular MIME type. |
| * If interfaces of the requested MIME type are found within the system, they are added |
| * to the UUIDs array. |
| * |
| * Also added to the UUIDs array will be all interfaces which have the requested MIME |
| * type as a base MIME type. This functionality can be turned off. |
| * |
| * @param aMimeType The MIME type of the desired interfaces |
| * @param aUuids A vector to hold the discovered UUIDs |
| * @param aExactUuidsOnly Turns on/off the retrival of UUIDs with aMimeType as a base type |
| * @param aContext Optional opaque data to be passed back to user with the command response |
| * @returns A unique command id for asynchronous completion |
| * @throw in case of failure, it leaves with an appropriate error |
| */ |
| virtual PVMFCommandId QueryUUID(const PvmfMimeString& aMimeType, |
| Oscl_Vector<PVUuid, OsclMemAllocator>& aUuids, |
| bool aExactUuidsOnly = false, |
| const OsclAny* aContext = NULL) = 0; |
| |
| |
| /** |
| * This API is to allow for extensibility of the PVMF Node interface. |
| * It allows a caller to ask for an instance of a particular interface object to be returned. |
| * The mechanism is analogous to the COM IUnknown method. The interfaces are identified with |
| * an interface ID that is a UUID as in DCE and a pointer to the interface object is |
| * returned if it is supported. Otherwise the returned pointer is NULL. |
| * TBD: Define the UIID, InterfacePtr structures |
| * |
| * @param aUuid The UUID of the desired interface |
| * @param aInterfacePtr The output pointer to the desired interface |
| * @param aContext Optional opaque data to be passed back to user with the command response |
| * @returns A unique command id for asynchronous completion |
| * @throw in case of failure, it leaves with an appropriate error |
| */ |
| virtual PVMFCommandId QueryInterface(const PVUuid& aUuid, |
| PVInterface*& aInterfacePtr, |
| const OsclAny* aContext = NULL) = 0; |
| |
| |
| /** |
| * Initializes the I/O component so that it is ready to operate. |
| * This API may need to reserve exclusive control, power up the device, and initialize |
| * the state of the device. |
| * Because it is not unusual for that process to take some time, the Init() API is asynchronous. |
| * A callback is made to the observer once the initialization is complete |
| * @param aContext Optional opaque data to be passed back to user with the command response |
| * @returns A unique command id for asynchronous completion |
| * @throw in case of failure, it leaves with an appropriate error |
| */ |
| virtual PVMFCommandId Init(const OsclAny* aContext = NULL) = 0; |
| |
| /** |
| * Resets the I/O component to free resources and to return to the pre-initialized state. |
| * Because it is not unusual for that process to take some time, the Reset() API is asynchronous. |
| * A callback is made to the observer once the initialization is complete |
| * @param aContext Optional opaque data to be passed back to user with the command response |
| * @returns A unique command id for asynchronous completion |
| * @throw in case of failure, it leaves with an appropriate error |
| */ |
| virtual PVMFCommandId Reset(const OsclAny* aContext = NULL) = 0; |
| |
| /** |
| * The start API call actually transitions the media I/O component to a state where it is |
| * ready to process media data. |
| * @param aContext Optional opaque data to be passed back to user with the command response |
| * @returns A unique command id for asynchronous completion |
| * @throw in case of failure, it leaves with an appropriate error |
| */ |
| |
| virtual PVMFCommandId Start(const OsclAny* aContext = NULL) = 0; |
| |
| /** |
| * This API is used to signal that input or output should be paused momentarily. Use Start() to resume. |
| * @param aContext Optional opaque data to be passed back to user with the command response |
| * @returns A unique command id for asynchronous completion |
| * @throw in case of failure, it leaves with an appropriate error |
| */ |
| |
| virtual PVMFCommandId Pause(const OsclAny* aContext = NULL) = 0; |
| |
| /** |
| * An API to complete any pending data. |
| * @param aContext Optional opaque data to be passed back to user with the command response |
| * @returns A unique command id for asynchronous completion |
| * @throw in case of failure, it leaves with an appropriate error |
| */ |
| |
| virtual PVMFCommandId Flush(const OsclAny* aContext = NULL) = 0; |
| |
| /** |
| * An API to discard any pending data without processing |
| * @param aContext Optional opaque data to be passed back to user with the command response |
| * @returns A unique command id for asynchronous completion |
| * @throw in case of failure, it leaves with an appropriate error |
| */ |
| |
| virtual PVMFCommandId DiscardData(const OsclAny* aContext = NULL) = 0; |
| |
| /** |
| * An API to discard any pending data without processing up to the specified timestamp value |
| * @param aTimestamp Timestamp value to discard data to |
| * @param aContext Optional opaque data to be passed back to user with the command response |
| * @returns A unique command id for asynchronous completion |
| * @throw in case of failure, it leaves with an appropriate error |
| */ |
| |
| virtual PVMFCommandId DiscardData(PVMFTimestamp aTimestamp, const OsclAny* aContext = NULL) = 0; |
| |
| /** |
| * The stop API call immediately stops the component. It doesn't complete any pending data |
| * and tries to stop as quickly as possible. |
| * @param aContext Optional opaque data to be passed back to user with the command response |
| * @returns A unique command id for asynchronous completion |
| * @throw in case of failure, it leaves with an appropriate error |
| */ |
| |
| virtual PVMFCommandId Stop(const OsclAny* aContext = NULL) = 0; |
| |
| /** |
| * Cancels a specific outstanding async command |
| * @param aCmd a specific async command to cancel |
| * @param aContext Optional opaque data to be passed back to |
| * user with the command response |
| * @returns A unique command id for asynchronous completion |
| * @throw if the cancel request cannot be accepted, it leaves with an |
| * appropriate error |
| */ |
| |
| virtual PVMFCommandId CancelCommand(PVMFCommandId aCmd, const OsclAny* aContext = NULL) = 0; |
| |
| /** |
| * Cancels all outstanding async commands |
| * @param aContext Optional opaque data to be passed back to |
| * user with the command response |
| * @returns A unique command id for asynchronous completion |
| * @throw if the cancel request cannot be accepted, it leaves with an |
| * appropriate error |
| */ |
| |
| virtual PVMFCommandId CancelAllCommands(const OsclAny* aContext = NULL) = 0; |
| |
| /** |
| * The purpose of this API is to indicate the thread context where the other APIs will be called. |
| * @throw in case of failure, it leaves with an appropriate error |
| */ |
| |
| virtual void ThreadLogon() = 0; |
| |
| /** |
| * Resets the thread context. No other APIs should be within the same thread context after this call. |
| * @throw in case of failure, it leaves with an appropriate error |
| */ |
| |
| virtual void ThreadLogoff() = 0; |
| }; |
| |
| |
| #endif //PVMI_MIO_CONTROL_H_INCLUDED |
