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 /** 19 * @file pvmf_meta_data_extension.h 20 * @brief Extension interface to retrieve metadata 21 */ 22 23 #ifndef PVMF_META_DATA_EXTENSION_H_INCLUDED 24 #define PVMF_META_DATA_EXTENSION_H_INCLUDED 25 26 #ifndef OSCL_BASE_H_INCLUDED 27 #include "oscl_base.h" 28 #endif 29 #ifndef PV_INTERFACE_H 30 #include "pv_interface.h" 31 #endif 32 #ifndef PV_UUID_H_INCLUDED 33 #include "pv_uuid.h" 34 #endif 35 #ifndef PVMF_FORMAT_TYPE_H_INCLUDED 36 #include "pvmf_event_handling.h" 37 #endif 38 #ifndef PVMF_META_DATA_TYPES_H_INCLUDED 39 #include "pvmf_meta_data_types.h" 40 #endif 41 #ifndef PVMI_KVP_H_INCLUDED 42 #include "pvmi_kvp.h" 43 #endif 44 45 #define PVMF_META_DATA_EXTENSION_INTERFACE_MIMETYPE "pvxxx/pvmf/pvmfmetadataextensioninterface" 46 47 // UUID for the extension interface 48 #define KPVMFMetadataExtensionUuid PVUuid(0x7DBD6D8D,0xB4CC,0x4887,0xB1,0x0B,0x7E,0xE6,0x48,0x47,0xB2,0x05) 49 50 /** 51 * PVMFMetadataExtensionInterface specifies the extension interface for metadata retrieval 52 */ 53 class PVMFMetadataExtensionInterface : public PVInterface 54 { 55 public: 56 /** 57 * Synchronous method to return the number of metadata keys for the specified query key string 58 * 59 * @param aQueryKeyString A NULL terminated character string specifying a subset of metadata keys to count. 60 * If the string is NULL, total number of all keys will be returned 61 * 62 * @returns The number of metadata keys 63 **/ 64 virtual uint32 GetNumMetadataKeys(char* aQueryKeyString = NULL) = 0; 65 66 /** 67 * Synchronous method to return the number of metadata values for the specified list of key strings 68 * 69 * @param aKeyList A reference to a metadata key list to specifying the values of interest to count 70 * 71 * @returns The number of metadata values based on the provided key list 72 **/ 73 virtual uint32 GetNumMetadataValues(PVMFMetadataList& aKeyList) = 0; 74 75 /** 76 * Asynchronous method to retrieve a list of metadata keys. The subset of all available keys in the node can 77 * be specified by providing a combination of query key string, starting index, and maximum number of keys to retrieve 78 * 79 * @param aSessionId The assigned node session ID to use for this request 80 * @param aKeyList A reference to a metadata key list to add the metadata keys 81 * @param aStartingKeyIndex Index into the node's total key list that corresponds to the first key entry to retrieve 82 * @param aMaxKeyEntries The maximum number of key entries to add to aKeyList. If there is no maximum, set to -1. 83 * @param aQueryKeyString Optional NULL terminated character string to select a subset of keys 84 * @param aContext Optional opaque data to be passed back to user with the command response 85 * 86 * @returns A unique command ID for asynchronous completion 87 **/ 88 virtual PVMFCommandId GetNodeMetadataKeys(PVMFSessionId aSessionId, 89 PVMFMetadataList& aKeyList, 90 uint32 aStartingKeyIndex, 91 int32 aMaxKeyEntries = -1, 92 char* aQueryKeyString = NULL, 93 const OsclAny* aContextData = NULL) = 0; 94 95 /** 96 * Asynchronous method to retrieve a list of metadata values. The subset of all available values in the node can 97 * be specified by providing a combination of key list, starting index, and maximum number of values to retrieve 98 * 99 * @param aSessionId The assigned node session ID to use for this request 100 * @param aKeyList A reference to a metadata key list specifying the metadata values to retrieve 101 * @param aValueList A reference to a metadata value list to add the metadata values 102 * @param aStartingValueIndex Index into the node's value list specified by the key list that corresponds to the first value entry to retrieve 103 * @param aMaxValueEntries The maximum number of value entries to add to aValueList. If there is no maximum, set to -1. 104 * @param aContext Optional opaque data to be passed back to user with the command response 105 * 106 * @returns A unique command ID for asynchronous completion 107 **/ 108 virtual PVMFCommandId GetNodeMetadataValues(PVMFSessionId aSessionId, 109 PVMFMetadataList& aKeyList, 110 Oscl_Vector<PvmiKvp, OsclMemAllocator>& aValueList, 111 uint32 aStartingValueIndex, 112 int32 aMaxValueEntries = -1, 113 const OsclAny* aContextData = NULL) = 0; 114 115 /** 116 * Synchronous method to free up the specified range of metadata keys in the list. It is assumed that caller of this function 117 * knows that start and end indices should correspond to metadata keys returned by this particular instance of the 118 * metadata extension interface using GetNodeMetadataKeys(). 119 * 120 * @param aKeyList A reference to a metadata key list to free the key entries 121 * @param aStartingKeyIndex Index into aKeyList that corresponds to the first key entry to release 122 * @param aEndKeyIndex Index into aKeyList that corresponds to the last key entry to release 123 * 124 * @returns PVMFSuccess if the release of specified keys succeeded. PVMFErrArgument if indices are invalid or the list is empty. 125 * PVMFFailure otherwise. 126 **/ 127 virtual PVMFStatus ReleaseNodeMetadataKeys(PVMFMetadataList& aKeyList, 128 uint32 aStartingKeyIndex, 129 uint32 aEndKeyIndex) = 0; 130 131 /** 132 * Synchronous method to free up the specified range of metadata values in the list. It is assumed that caller of this function 133 * knows that start and end indices should correspond to metadata values returned by this particular instance of the 134 * metadata extension interface using GetNodeMetadataValues(). 135 * 136 * @param aValueList A reference to a metadata value list to free the value entries 137 * @param aStartingValueIndex Index into aValueList that corresponds to the first value entry to release 138 * @param aEndValueIndex Index into aValueList that corresponds to the last value entry to release 139 * 140 * @returns PVMFSuccess if the release of specified values succeeded. PVMFErrArgument if indices are invalid or the list is empty. 141 * PVMFFailure otherwise. 142 **/ 143 virtual PVMFStatus ReleaseNodeMetadataValues(Oscl_Vector<PvmiKvp, OsclMemAllocator>& aValueList, 144 uint32 aStartingValueIndex, 145 uint32 aEndValueIndex) = 0; 146 147 // From PVInterface 148 virtual void addRef() = 0; 149 150 virtual void removeRef() = 0; 151 152 virtual bool queryInterface(const PVUuid& uuid, PVInterface*& iface) = 0; 153 }; 154 155 #endif // PVMF_META_DATA_EXTENSION_H_INCLUDED 156