1 /* ------------------------------------------------------------------ 2 * Copyright (C) 1998-2009 PacketVideo 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either 13 * express or implied. 14 * See the License for the specific language governing permissions 15 * and limitations under the License. 16 * ------------------------------------------------------------------- 17 */ 18 // -*- c++ -*- 19 // = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 20 21 // P V M I _ M I O _ C O N T R O L 22 23 // = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 24 25 /*! \addtogroup pvmimiocontrol PvmiMioControl 26 * 27 * @{ 28 */ 29 30 31 /*! \file pvmi_mio_control.h 32 \brief This file contains the abstractions for media input-output control. 33 */ 34 35 #ifndef PVMI_MIO_CONTROL_H_INCLUDED 36 #define PVMI_MIO_CONTROL_H_INCLUDED 37 38 /* 39 This class defines an abstract interface for media input-output control 40 */ 41 #ifndef OSCL_BASE_H_INCLUDED 42 #include "oscl_base.h" 43 #endif 44 #ifndef OSCL_VECTOR_H_INCLUDED 45 #include "oscl_vector.h" 46 #endif 47 #ifndef PV_UUID_H_INCLUDED 48 #include "pv_uuid.h" 49 #endif 50 #ifndef PV_INTERFACE_H_INCLUDED 51 #include "pv_interface.h" 52 #endif 53 #ifndef PVMI_MEDIA_TRANSFER_H_INCLUDED 54 #include "pvmi_media_transfer.h" 55 #endif 56 #ifndef PVMI_MEDIA_IO_OBSERVER_H_INCLUDED 57 #include "pvmi_media_io_observer.h" 58 #endif 59 #ifndef PVMF_RETURN_CODES_H_INCLUDED 60 #include "pvmf_return_codes.h" 61 #endif 62 #ifndef PVMF_FORMAT_TYPES_H_INCLUDED 63 #include "pvmf_format_type.h" 64 #endif 65 #ifndef PVMI_KVP_H_INCLUDED 66 #include "pvmi_kvp.h" 67 #endif 68 69 /** \class PvmiMIOControl 70 ** This class defines an abstract interface for media input-output control 71 */ 72 73 class PvmiMIOControl 74 { 75 76 public: 77 ~PvmiMIOControl()78 virtual ~PvmiMIOControl() {} 79 80 /** 81 * This method establishes a connection to the media I/O component. This is a prerequisite 82 * to any other interaction 83 * 84 * @param aSession This output parametre will be filled in with an opaque session ID 85 * which will be used to identify the connection session. 86 * @param aObserver Specifies an observer class to be registered 87 * for handling the results of asynchronous requests 88 * @returns PVMFSuccess if the operation is succesful. PVMFFailure otherwise. 89 */ 90 91 virtual PVMFStatus connect(PvmiMIOSession& aSession, 92 PvmiMIOObserver* aObserver) = 0; 93 94 95 96 /** 97 * Once all interaction with the media I/O component is complete, the session can be 98 * terminated with the disconnect call. Any pending asynchronous requests associated 99 * with that session will be cancelled and a cancel status will be returned for each 100 * them using the observer callback. 101 * 102 * @param aSession The opaque session ID which is used to identify the connection session. 103 * @returns PvmiSuccess if operation is succesful. PvmiFailure otherwise. 104 */ 105 106 virtual PVMFStatus disconnect(PvmiMIOSession aSession) = 0; 107 108 109 /** 110 * The media I/O component provides a factory API to allocate and return a reference to PvmiMediaTransfer interface. 111 * The call succeeds only if the supplied parameters to the function are within the capabilities of the 112 * component as specified in the previous section. 113 * 114 * @param aSession The opaque session ID which is used to identify the connection session. 115 * @param read_formats list of formats that will be used for reading with this end point 116 * @param read_flags Specify the modes that will be used for reading. 117 * @param write_formats list of formats that will be used for writing this end point 118 * @param write_flags Specify the modes that will be used for reading. 119 * @returns If all the parameters are verified, a reference to a PvmiMediaTransfer 120 * interface shall be returned. 121 * @throw The function shall leave with PvmfErrNotSupported, 122 * if any of the parameters are outside the capabilities 123 * of the component. 124 */ 125 126 virtual PvmiMediaTransfer* createMediaTransfer( 127 PvmiMIOSession& aSession, 128 PvmiKvp* read_formats = NULL, int32 read_flags = 0, 129 PvmiKvp* write_formats = NULL, int32 write_flags = 0) = 0; 130 131 132 133 /** 134 * A media transfer session can be terminated by using this API 135 * 136 * @param aSession The opaque session ID which is used to identify the connection session. 137 * @param media_transfer list of formats that will be used for reading with this end point 138 * @returns A pre-requisite to deleting a PvmiMediaTransfer interface is 139 * that any outstanding read or write buffers must be returned 140 * to the interface. 141 * @throw The function shall leave with PvmfErrBusy if an attempt is made 142 * to delete it while there are outstanding buffers. 143 */ 144 145 virtual void deleteMediaTransfer( 146 PvmiMIOSession& aSession, 147 PvmiMediaTransfer* media_transfer) = 0; 148 149 150 // Async requests that will trigger callback events 151 /** 152 * This API is to allow for extensibility of the PVMF Node interface. 153 * It allows a caller to ask for all UUIDs associated with a particular MIME type. 154 * If interfaces of the requested MIME type are found within the system, they are added 155 * to the UUIDs array. 156 * 157 * Also added to the UUIDs array will be all interfaces which have the requested MIME 158 * type as a base MIME type. This functionality can be turned off. 159 * 160 * @param aMimeType The MIME type of the desired interfaces 161 * @param aUuids A vector to hold the discovered UUIDs 162 * @param aExactUuidsOnly Turns on/off the retrival of UUIDs with aMimeType as a base type 163 * @param aContext Optional opaque data to be passed back to user with the command response 164 * @returns A unique command id for asynchronous completion 165 * @throw in case of failure, it leaves with an appropriate error 166 */ 167 virtual PVMFCommandId QueryUUID(const PvmfMimeString& aMimeType, 168 Oscl_Vector<PVUuid, OsclMemAllocator>& aUuids, 169 bool aExactUuidsOnly = false, 170 const OsclAny* aContext = NULL) = 0; 171 172 173 /** 174 * This API is to allow for extensibility of the PVMF Node interface. 175 * It allows a caller to ask for an instance of a particular interface object to be returned. 176 * The mechanism is analogous to the COM IUnknown method. The interfaces are identified with 177 * an interface ID that is a UUID as in DCE and a pointer to the interface object is 178 * returned if it is supported. Otherwise the returned pointer is NULL. 179 * TBD: Define the UIID, InterfacePtr structures 180 * 181 * @param aUuid The UUID of the desired interface 182 * @param aInterfacePtr The output pointer to the desired interface 183 * @param aContext Optional opaque data to be passed back to user with the command response 184 * @returns A unique command id for asynchronous completion 185 * @throw in case of failure, it leaves with an appropriate error 186 */ 187 virtual PVMFCommandId QueryInterface(const PVUuid& aUuid, 188 PVInterface*& aInterfacePtr, 189 const OsclAny* aContext = NULL) = 0; 190 191 192 /** 193 * Initializes the I/O component so that it is ready to operate. 194 * This API may need to reserve exclusive control, power up the device, and initialize 195 * the state of the device. 196 * Because it is not unusual for that process to take some time, the Init() API is asynchronous. 197 * A callback is made to the observer once the initialization is complete 198 * @param aContext Optional opaque data to be passed back to user with the command response 199 * @returns A unique command id for asynchronous completion 200 * @throw in case of failure, it leaves with an appropriate error 201 */ 202 virtual PVMFCommandId Init(const OsclAny* aContext = NULL) = 0; 203 204 /** 205 * Resets the I/O component to free resources and to return to the pre-initialized state. 206 * Because it is not unusual for that process to take some time, the Reset() API is asynchronous. 207 * A callback is made to the observer once the initialization is complete 208 * @param aContext Optional opaque data to be passed back to user with the command response 209 * @returns A unique command id for asynchronous completion 210 * @throw in case of failure, it leaves with an appropriate error 211 */ 212 virtual PVMFCommandId Reset(const OsclAny* aContext = NULL) = 0; 213 214 /** 215 * The start API call actually transitions the media I/O component to a state where it is 216 * ready to process media data. 217 * @param aContext Optional opaque data to be passed back to user with the command response 218 * @returns A unique command id for asynchronous completion 219 * @throw in case of failure, it leaves with an appropriate error 220 */ 221 222 virtual PVMFCommandId Start(const OsclAny* aContext = NULL) = 0; 223 224 /** 225 * This API is used to signal that input or output should be paused momentarily. Use Start() to resume. 226 * @param aContext Optional opaque data to be passed back to user with the command response 227 * @returns A unique command id for asynchronous completion 228 * @throw in case of failure, it leaves with an appropriate error 229 */ 230 231 virtual PVMFCommandId Pause(const OsclAny* aContext = NULL) = 0; 232 233 /** 234 * An API to complete any pending data. 235 * @param aContext Optional opaque data to be passed back to user with the command response 236 * @returns A unique command id for asynchronous completion 237 * @throw in case of failure, it leaves with an appropriate error 238 */ 239 240 virtual PVMFCommandId Flush(const OsclAny* aContext = NULL) = 0; 241 242 /** 243 * An API to discard any pending data without processing 244 * @param aContext Optional opaque data to be passed back to user with the command response 245 * @returns A unique command id for asynchronous completion 246 * @throw in case of failure, it leaves with an appropriate error 247 */ 248 249 virtual PVMFCommandId DiscardData(const OsclAny* aContext = NULL) = 0; 250 251 /** 252 * An API to discard any pending data without processing up to the specified timestamp value 253 * @param aTimestamp Timestamp value to discard data to 254 * @param aContext Optional opaque data to be passed back to user with the command response 255 * @returns A unique command id for asynchronous completion 256 * @throw in case of failure, it leaves with an appropriate error 257 */ 258 259 virtual PVMFCommandId DiscardData(PVMFTimestamp aTimestamp, const OsclAny* aContext = NULL) = 0; 260 261 /** 262 * The stop API call immediately stops the component. It doesn't complete any pending data 263 * and tries to stop as quickly as possible. 264 * @param aContext Optional opaque data to be passed back to user with the command response 265 * @returns A unique command id for asynchronous completion 266 * @throw in case of failure, it leaves with an appropriate error 267 */ 268 269 virtual PVMFCommandId Stop(const OsclAny* aContext = NULL) = 0; 270 271 /** 272 * Cancels a specific outstanding async command 273 * @param aCmd a specific async command to cancel 274 * @param aContext Optional opaque data to be passed back to 275 * user with the command response 276 * @returns A unique command id for asynchronous completion 277 * @throw if the cancel request cannot be accepted, it leaves with an 278 * appropriate error 279 */ 280 281 virtual PVMFCommandId CancelCommand(PVMFCommandId aCmd, const OsclAny* aContext = NULL) = 0; 282 283 /** 284 * Cancels all outstanding async commands 285 * @param aContext Optional opaque data to be passed back to 286 * user with the command response 287 * @returns A unique command id for asynchronous completion 288 * @throw if the cancel request cannot be accepted, it leaves with an 289 * appropriate error 290 */ 291 292 virtual PVMFCommandId CancelAllCommands(const OsclAny* aContext = NULL) = 0; 293 294 /** 295 * The purpose of this API is to indicate the thread context where the other APIs will be called. 296 * @throw in case of failure, it leaves with an appropriate error 297 */ 298 299 virtual void ThreadLogon() = 0; 300 301 /** 302 * Resets the thread context. No other APIs should be within the same thread context after this call. 303 * @throw in case of failure, it leaves with an appropriate error 304 */ 305 306 virtual void ThreadLogoff() = 0; 307 }; 308 309 310 #endif //PVMI_MIO_CONTROL_H_INCLUDED 311