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 _ C A P A B I L I T Y _ A N D _ C O N F I G 22 23 // = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = 24 25 /*! \addtogroup pvmicapability PvmiCapability 26 * 27 * @{ 28 */ 29 30 31 /*! \file pvmi_config_and_capability.h 32 \brief This file contains the abstractions for configuration and capability exchange 33 */ 34 35 #ifndef PVMI_CONFIG_AND_CAPABILITY_H_INCLUDED 36 #define PVMI_CONFIG_AND_CAPABILITY_H_INCLUDED 37 38 #ifndef OSCL_BASE_H_INCLUDED 39 #include "oscl_base.h" 40 #endif 41 #ifndef PVMF_EVENT_HANDLING_H_INCLUDED 42 #include "pvmf_event_handling.h" 43 #endif 44 #ifndef PVMF_RETURN_CODES_H_INCLUDED 45 #include "pvmf_return_codes.h" 46 #endif 47 #ifndef PVMI_CONFIG_AND_CAPABILITY_OBSERVER_H_INCLUDED 48 #include "pvmi_config_and_capability_observer.h" 49 #endif 50 #ifndef PVMI_KVP_H_INCLUDED 51 #include "pvmi_kvp.h" 52 #endif 53 54 #define PVMI_CAPABILITY_AND_CONFIG_PVUUID PVUuid(0xa07419ac,0x20c5,0x4c2e,0x85,0x56,0xc9,0x2f,0xc6,0x74,0xf3,0xa7) 55 typedef void* PvmiCapabilityContext; 56 57 /** 58 * Abstract interface for capability and configuration of PVMI components 59 */ 60 class PvmiCapabilityAndConfig: public PVInterface 61 { 62 public: ~PvmiCapabilityAndConfig()63 virtual ~PvmiCapabilityAndConfig() {} 64 65 /** 66 * This method allows setting of an observer to listen for completion of asynchronous commands. 67 * 68 * @param aObserver The observer for status 69 */ 70 virtual void setObserver(PvmiConfigAndCapabilityCmdObserver* aObserver) = 0; 71 72 /** 73 * This method returns a list of parameters describing the attribute specified in the query. 74 * The attributes that can be requested are capabilities, current parameter setting and default 75 * setting. 76 * 77 * @param aSession An Opaque session ID 78 * @param aIdentifier MIME string that has the specific query 79 * @param aParameters An output pointer to an array of parameters relevant to the query 80 * @param num_parameter_elements Number of the elements in the returned array of parameters 81 * @param aContext The context in which we expect to restrict our search 82 * @returns PVMFSuccess if the operation is succesful or PVMFErrArgument 83 * if the format of the key(s) is invalid 84 */ 85 virtual PVMFStatus getParametersSync(PvmiMIOSession aSession, 86 PvmiKeyType aIdentifier, 87 PvmiKvp*& aParameters, 88 int& num_parameter_elements, 89 PvmiCapabilityContext aContext) = 0; 90 91 92 /** 93 * This method releases a list of parameters back to the component that allocated it. 94 * The caller should remove any references to the parameters and structures contained within after a 95 * call to this function. 96 * 97 * @param aSession The Opaque session ID 98 * @param aParameters A pointer to an array of parameters relevant to the query 99 * @param num_elements Number of the elements in the returned array of parameters 100 * @returns PVMFSuccess if the operation is succesful or PVMFFailure 101 * if an error has occured during the operation 102 */ 103 virtual PVMFStatus releaseParameters(PvmiMIOSession aSession, 104 PvmiKvp* aParameters, 105 int num_elements) = 0; 106 107 /** 108 * This method is used to create a context within a capability exchange session. 109 * 110 * @param aSession The Opaque session ID 111 * @param aContext Will contain the handle to the newly created context 112 * @returns This function can leave with the following error codes 113 * PVMFErrNotSupported, if the component does not suppport contexts 114 * PVMFErrExceeded, if the number of allowable contexts is exceeded 115 */ 116 virtual void createContext(PvmiMIOSession aSession, PvmiCapabilityContext& aContext) = 0; 117 118 /** 119 * This method defines the space of a context.When a context is created, its space is the gamut 120 * of capabilities of the component.This API defines the new space of the context as the 121 * intersection of the current space with the space defined by the parameters. 122 * 123 * 124 * @param aSession The Opaque session ID 125 * @param aContext The context that we expect to configure 126 * @param aParameters An array of key-value pairs that should be associated with this context 127 * @param num_parameter_elements Number of the elements in the array of parameters. 128 * @returns The function can leave with the following error codes 129 * PVMFErrArgument if invalid arguments are passed 130 * PVMFFailure if there is not intersection between the parameter space and the space of the context. 131 */ 132 virtual void setContextParameters(PvmiMIOSession aSession, PvmiCapabilityContext& aContext, 133 PvmiKvp* aParameters, int num_parameter_elements) = 0; 134 135 /** 136 * A context can deleted using the deleteContext API. 137 * A user of the context should remove all references to the context once it has been deleted. 138 * 139 * @param aSession The Opaque session ID 140 * @param aContext Will contain a handle to the context 141 * @returns This function can leave with the following error codes 142 */ 143 virtual void DeleteContext(PvmiMIOSession aSession, 144 PvmiCapabilityContext& aContext) = 0; 145 146 /** 147 * This method is to be used to set one or more parameter values, legal values for which 148 * have been previously queried using the getParametersSync API. 149 * 150 * @param aSession The Opaque session ID 151 * @param aParameters An array of key-value pairs that should be used to set the parametres 152 * @param num_elements Number of the elements in the array of parameters. 153 * @param aRet_kvp ret_kvp is an output parameter to be used in case of errors. 154 * It points to the first input key-value pair that caused an error 155 * @returns The function can leave with the following error codes 156 * PVMFErrArgument if invalid arguments are passed. 157 * In this case, Ret_kvp output argument is set to point to 158 * the argument that caused the error. 159 */ 160 virtual void setParametersSync(PvmiMIOSession aSession, 161 PvmiKvp* aParameters, 162 int num_elements, 163 PvmiKvp * & aRet_kvp) = 0; 164 165 /** 166 * This is an asynchronous version the setParameters method. 167 * The memory for the parameters shall be valid and not modified until 168 * the completion of processing of this command 169 * 170 * @param aSession The Opaque session ID 171 * @param aParameters An array of key-value pairs that should be used to set the parametres 172 * @param num_elements Number of the elements in the array of parameters. 173 * @param aRet_kvp ret_kvp is an output parameter to be used in case of errors. 174 * It points to the first input key-value pair that caused an error 175 * @returns TBD. PVMFSuccess if the operation was succesful, PVMFFailure otherwise 176 */ 177 virtual PVMFCommandId setParametersAsync(PvmiMIOSession aSession, 178 PvmiKvp* aParameters, 179 int num_elements, 180 PvmiKvp*& aRet_kvp, 181 OsclAny* context = NULL) = 0; 182 183 /** 184 * This method is used to query the complexity of a components capability tree. 185 * The modulus shall be used to determine the master in a peer-peer capability exchange. 186 * 187 * @param aSession The Opaque session ID 188 * @returns TBD. 189 */ 190 virtual uint32 getCapabilityMetric(PvmiMIOSession aSession) = 0; 191 192 /** 193 * This method verifies if a mode of operation as identified by a set of key-value pairs 194 * is within the capabilities of the component, based on its current state of operation. 195 * If the call returns success, calls to SetParameter using the same parameters should also 196 * be successful, given the same state of the component. 197 * 198 * @param aSession The Opaque session ID 199 * @param aParameters An array of key-value pairs that should be used to verify the parametres 200 * @param num_elements Number of the elements in the array of parameters. 201 * @returns TBD. PVMFSuccess if the operation was succesful, PVMFFailure otherwise 202 */ 203 virtual PVMFStatus verifyParametersSync(PvmiMIOSession aSession, 204 PvmiKvp* aParameters, int num_elements) = 0; 205 206 //from PVInterface queryInterface(const PVUuid & aUuid,PVInterface * & aInterfacePtr)207 virtual bool queryInterface(const PVUuid& aUuid 208 , PVInterface*& aInterfacePtr) 209 { 210 if (aUuid == PVMI_CAPABILITY_AND_CONFIG_PVUUID) 211 { 212 aInterfacePtr = this; 213 return true; 214 } 215 return false; 216 } addRef()217 virtual void addRef() 218 {} removeRef()219 virtual void removeRef() 220 {} 221 222 protected: 223 PvmiConfigAndCapabilityCmdObserver* ciObserver; 224 }; 225 226 #endif //PVMI_CONFIG_AND_CAPABILITY_H_INCLUDED 227