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 /*! \addtogroup pvmimiocontrol PvmiMediaTransfer 19 * 20 * @{ 21 */ 22 23 24 /*! \file pvmi_media_transfer.h 25 \brief Defines an abstract interface for media transfer. 26 */ 27 28 #ifndef PVMI_MEDIA_TRANSFER_H_INCLUDED 29 #define PVMI_MEDIA_TRANSFER_H_INCLUDED 30 31 #ifndef OSCL_BASE_H_INCLUDED 32 #include "oscl_base.h" 33 #endif 34 #ifndef OSCL_MEM_H_INCLUDED 35 #include "oscl_mem.h" 36 #endif 37 #ifndef PVMF_TIMESTAMP_H_INCLUDED 38 #include "pvmf_timestamp.h" 39 #endif 40 #ifndef PVMF_RETURN_CODES_H_INCLUDED 41 #include "pvmf_return_codes.h" 42 #endif 43 #ifndef PVMF_EVENT_HANDLING_H_INCLUDED 44 #include "pvmf_event_handling.h" 45 #endif 46 47 /** status bitmasks */ 48 #define PVMI_MEDIAXFER_STATUS_WRITE 0x01 49 #define PVMI_MEDIAXFER_STATUS_READ 0x02 50 51 /** values for format types */ 52 #define PVMI_MEDIAXFER_FMT_TYPE_DATA 1 53 #define PVMI_MEDIAXFER_FMT_TYPE_COMMAND 2 54 #define PVMI_MEDIAXFER_FMT_TYPE_NOTIFICATION 3 55 56 /** default values for format index in cases where it is not negotiated 57 between the peers */ 58 #define PVMI_MEDIAXFER_FMT_INDEX_DATA 1 59 #define PVMI_MEDIAXFER_FMT_INDEX_FMT_SPECIFIC_INFO 2 60 #define PVMI_MEDIAXFER_FMT_INDEX_END_OF_STREAM 3 61 #define PVMI_MEDIAXFER_FMT_INDEX_RE_CONFIG_NOTIFICATION 4 62 63 /** Data in writeAsync is an PVMFAsyncEvent object of PVMFInfoEvent event category */ 64 #define PVMI_MEDIAXFER_FMT_INDEX_INFO_EVENT 5 65 66 /** Data in writeAsync is an PVMFAsyncEvent object of PVMFErrorEvent event category */ 67 #define PVMI_MEDIAXFER_FMT_INDEX_ERROR_EVENT 6 68 69 70 /* Format for flags that are send as part of write async */ 71 #define PVMI_MEDIAXFER_MEDIA_DATA_FLAG_NONE 0x00000000 72 #define PVMI_MEDIAXFER_MEDIA_DATA_FLAG_MARKER_BIT 0x00000001 73 #define PVMI_MEDIAXFER_MEDIA_DATA_FLAG_DURATION_AVAILABLE_BIT 0x00000002 74 #define PVMI_MEDIAXFER_MEDIA_DATA_FLAG_NO_RENDER_BIT 0x00000004 75 76 /* Data structure to hold info associated with media transfer */ 77 typedef struct __PvmiMediaXferHeader 78 { 79 uint32 seq_num; 80 PVMFTimestamp timestamp; 81 uint32 flags; 82 uint32 duration; 83 uint32 stream_id; 84 OsclAny *private_data_ptr; 85 uint32 private_data_length; 86 } PvmiMediaXferHeader; 87 88 /** 89 * This class defines an abstract interface for media transfer between two connected 90 * PvmiMediaTransfer objects. 91 */ 92 class PvmiMediaTransfer 93 { 94 95 public: ~PvmiMediaTransfer()96 virtual ~PvmiMediaTransfer() {} 97 98 /** 99 * This method is used to set a peer for Media Transfer 100 * 101 * @param aPeer The peer that would be used for media transfer 102 * @throw In case of failure, leaves with an appropriate error 103 */ 104 virtual void setPeer(PvmiMediaTransfer* aPeer) = 0; 105 106 /** 107 * This method specifies which memory allocators shall be used for input and output 108 * 109 * @param read_write_alloc Specifies the read and write allocator 110 * 111 * @throw If the choice of allocator is unacceptable, the function 112 * leaves with PvmfErrNotSupported. 113 */ 114 virtual void useMemoryAllocators(OsclMemAllocator* read_write_alloc) = 0; 115 116 117 /** 118 * This method is used by a component to send data actively to its peer. 119 * 120 * @param format_type Identifies whether the message that is being written is data/command/notification 121 * @param format_index It is used if multiple simultaneous formats are used in media transfer 122 * @param data Specifies the media data 123 * @param data_len Specifies the media data length 124 * @param data_header_info Contains info (timestamp, flags,...) associated with the data 125 * @param aContext Optional opaque data to be passed back to 126 * user with the writeComplete response 127 * 128 * @returns The function returns a unique command id if accepted. 129 * @throw if request not accepted, it leaves with an appropriate error code 130 * If the function should leave due to a recoverable problem like an 131 * overflow condition, the caller should wait for the status 132 * to change before attempting to send more media data. 133 */ 134 virtual PVMFCommandId writeAsync( 135 uint8 format_type, int32 format_index, 136 uint8* data, uint32 data_len, 137 const PvmiMediaXferHeader& data_header_info, 138 OsclAny* aContext = NULL) = 0; 139 140 /** 141 * This method is used to report completion of write operation. 142 * It can also be assumed that the corresponding data buffer can now be 143 * reused 144 * 145 * @param aStatus status parameter indicates whether the write 146 * operation corresponding to write_cmd_id was 147 * successful or not. 148 * @param write_cmd_id corresponding to write_cmd_id returned in writeAsyn 149 * @param aContext The Opaque context, same as the one sent 150 * in writeAsync request 151 * 152 * @throw in case of failure, leaves with an appropriate error 153 */ 154 virtual void writeComplete( 155 PVMFStatus aStatus, 156 PVMFCommandId write_cmd_id, 157 OsclAny* aContext) = 0; 158 159 /** 160 * This API should be used on its peer by a component to receive data actively 161 * 162 * @param data, The read buffer. 163 * @param max_data_len The maximum length of the read buffer 164 * @param aContext The context parameter is an opaque handle provided by the caller. 165 * @param formats, num_formats Specify the indices of media data that may be read into this buffer 166 * 167 * @returns The function returns a unique command id if accepted. 168 * @throw if request not accepted, it leaves with an appropriate error code 169 * If the function should leave due to a recoverable problem like an 170 * underflow condition, the caller should wait for the status 171 * to change before attempting to send more media data. 172 */ 173 virtual PVMFCommandId readAsync( 174 uint8* data, uint32 max_data_len, 175 OsclAny* aContext = NULL, 176 int32* formats = NULL, uint16 num_formats = 0) = 0; 177 178 /** 179 * This function signals the completion of the read operation 180 * 181 * @param aStatus Status parameter indicates whether the read 182 * operation corresponding to read_cmd_id was 183 * successful or not. 184 * @param read_cmd_id Corresponding to read_cmd_id returned in readAsync 185 * @param format_index The format_index parameter specifies the format 186 * of the data that was read 187 * @param data_header_info Contains info (timestamp, flags,...) associated with the data 188 * @param aContext The Opaque context, same as the one sent 189 * in readAsync request 190 * 191 * @throw in case of failure, leaves with an appropriate error 192 */ 193 virtual void readComplete( 194 PVMFStatus aStatus, 195 PVMFCommandId read_cmd_id, 196 int32 format_index, 197 const PvmiMediaXferHeader& data_header_info, 198 OsclAny* aContext) = 0; 199 200 /** 201 * A media I/O component may need to signal changes in its operating 202 * status like suspension/resumption of read/write operations. 203 * This is useful for recovering from temporary failures during read 204 * and write operations. The status update is communicated using the i 205 * following function. 206 * 207 * @param status_flags The status_flags parameter provides the read, 208 * write and error status using bitmasks i 209 * PVMI_MEDIAXFER_STATUS_READ, 210 * PVMI_MEDIAXFER_STATUS_WRITE. 211 * A status of 1 indicates OK and 0 indicates Not OK. 212 * 213 * @throw in case of failure, leaves with an appropriate error 214 */ 215 virtual void statusUpdate(uint32 status_flags) = 0; 216 217 /** 218 * Any outstanding writeAsync or readAsync commands may be cancelled by 219 * specifying the unique command id that was returned for the function 220 * call. The component shall attempt to cancel the operation 221 * if possible, although it cannot guarantee that the operation will be 222 * cancelled. 223 * 224 * @param command_id unique command_id returned by writeAsyn or readAsync 225 * 226 * @throw If the cancel request cannot be accepted, it leaves with an 227 * appropriate error 228 */ 229 virtual void cancelCommand(PVMFCommandId command_id) = 0; 230 231 /** 232 * Cancels all outstanding writeAsync or readAsync commands. 233 * The component shall attempt to cancel the operations if possible, 234 * although it cannot guarantee that the operations will be cancelled. 235 * 236 * @throw If the cancel request cannot be accepted, it leaves with an 237 * appropriate error 238 */ 239 virtual void cancelAllCommands() = 0; 240 }; 241 242 #endif // PVMI_MEDIA_TRANSFER_H_INCLUDED 243