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 #ifndef PVMF_CPMPLUGIN_INTERFACE_H_INCLUDED 19 #define PVMF_CPMPLUGIN_INTERFACE_H_INCLUDED 20 21 #ifndef OSCL_BASE_H_INCLUDED 22 #include "oscl_base.h" 23 #endif 24 #ifndef OSCL_TYPES_H_INCLUDED 25 #include "oscl_types.h" 26 #endif 27 #ifndef PV_UUID_H_INCLUDED 28 #include "pv_uuid.h" 29 #endif 30 #ifndef PV_INTERFACE_H_INCLUDED 31 #include "pv_interface.h" 32 #endif 33 #ifndef PVMF_NODE_INTERFACE_H_INCLUDED 34 #include "pvmf_node_interface.h" 35 #endif 36 #ifndef CPM_TYPES_H 37 #include "cpm_types.h" 38 #endif 39 40 /** 41 * PVMFCpmPluginCmdStatusObserver Class 42 * 43 * PVMFCpmPluginCmdStatusObserver is the PVMF CPM Plugin observer class for 44 * notifying the status of issued command messages. The API provides a mechanism 45 * for the status of each command to be passed back along with context specific 46 * information where applicable. 47 * Applications using the module must have a class derived from 48 * PVMFCpmPluginCmdStatusObserver and implement the pure virtual function in 49 * order to receive event notifications from the plugin. 50 **/ 51 class PVMFCPMPluginCmdStatusObserver 52 { 53 public: 54 /** 55 * Handle an event that has been generated. 56 * @param "aResponse" "The response to a previously issued command." 57 */ 58 virtual void CPMPluginCommandCompleted(const PVMFCmdResp& aResponse) = 0; 59 virtual ~PVMFCPMPluginCmdStatusObserver() {} 60 }; 61 62 63 #define PVMF_CPMPLUGIN_DEFAULT_SESSION_RESERVE 10 64 65 class PVMFCPMPluginSession 66 { 67 public: 68 PVMFCPMPluginSession(PVMFSessionId aId, PVMFCPMPluginCmdStatusObserver& aObs) 69 : iId(aId) 70 , iCmdStatusObserver(&aObs) 71 {} 72 PVMFSessionId iId; 73 PVMFCPMPluginCmdStatusObserver* iCmdStatusObserver; 74 }; 75 76 /** 77 * Content Policy Manager Service Plugin interface 78 */ 79 class PVMFCPMPluginInterface 80 { 81 public: 82 virtual ~PVMFCPMPluginInterface() 83 { 84 iSessions.clear(); 85 } 86 87 virtual PVMFSessionId Connect(PVMFCPMPluginCmdStatusObserver &aObs) 88 { 89 PVMFCPMPluginSession session(iSessions.size(), aObs); 90 iSessions.push_back(session); 91 if (!iLoggedOn) 92 { 93 ThreadLogon(); 94 iLoggedOn = true; 95 } 96 return session.iId; 97 } 98 99 virtual PVMFStatus Disconnect(PVMFSessionId aSessionId) 100 { 101 for (uint32 i = 0; i < iSessions.size(); i++) 102 { 103 if (iSessions[i].iId == aSessionId) 104 { 105 iSessions.erase(&iSessions[i]); 106 if (iLoggedOn 107 && iSessions.size() == 0) 108 { 109 ThreadLogoff(); 110 iLoggedOn = false; 111 } 112 return PVMFSuccess; 113 } 114 } 115 return PVMFFailure; 116 } 117 118 /** 119 * This API is to allow for extensibility of the CPM plugin interface. 120 * It allows a caller to ask for all UUIDs associated with a particular MIME type. 121 * If interfaces of the requested MIME type are found within the system, they are added 122 * to the UUIDs array. 123 * 124 * Also added to the UUIDs array will be all interfaces which have the requested MIME 125 * type as a base MIME type. This functionality can be turned off. 126 * 127 * @param aMimeType The MIME type of the desired interfaces 128 * @param aUuids A vector to hold the discovered UUIDs 129 * @param aExactUuidsOnly Turns on/off the retrival of UUIDs with aMimeType as a base type 130 * @param aContext Optional opaque data to be passed back to user with the command response 131 * @returns A unique command id for asynchronous completion 132 */ 133 virtual PVMFCommandId QueryUUID(PVMFSessionId aSession, 134 const PvmfMimeString& aMimeType, 135 Oscl_Vector<PVUuid, OsclMemAllocator>& aUuids, 136 bool aExactUuidsOnly = true, 137 const OsclAny* aContext = NULL) = 0; 138 139 /** 140 * This API is to allow for extensibility of the CPM Plugin interface. 141 * It allows a caller to ask for an instance of a particular interface object to be returned. 142 * The mechanism is analogous to the COM IUnknown method. The interfaces are identified with 143 * an interface ID that is a UUID as in DCE and a pointer to the interface object is 144 * returned if it is supported. Otherwise the returned pointer is NULL. 145 * 146 * @param aUuid The UUID of the desired interface 147 * @param aInterfacePtr The output pointer to the desired interface 148 * @param aContext Optional opaque data to be passed back to user with the command response 149 * @returns A unique command id for asynchronous completion 150 */ 151 virtual PVMFCommandId QueryInterface(PVMFSessionId aSession, 152 const PVUuid& aUuid, 153 PVInterface*& aInterfacePtr, 154 const OsclAny* aContext = NULL) = 0; 155 156 /** 157 * Starts initialization of the plugin. 158 * At the minimum, the plugin should be 159 * ready to authenticate user after initialization is complete 160 **/ 161 virtual PVMFCommandId Init(PVMFSessionId aSession, 162 const OsclAny* aContext = NULL) = 0; 163 164 /** 165 * Resets the plugin. 166 * The plugin should relinquish all resources that is 167 * has acquired as part of the initialization process and should be ready 168 * to be deleted when this completes. 169 **/ 170 virtual PVMFCommandId Reset(PVMFSessionId aSession, 171 const OsclAny* aContext = NULL) = 0; 172 173 virtual PVMFStatus SetSourceInitializationData(OSCL_wString& aSourceURL, 174 PVMFFormatType& aSourceFormat, 175 OsclAny* aSourceData) = 0; 176 177 /** 178 * Retrieves the mapped CPM content type for a passed in source. This could 179 * be types based on DRM version or content rating etc 180 **/ 181 virtual PVMFCPMContentType GetCPMContentType() = 0; 182 183 /** 184 * Optional API to retrieve the original filename of a protected file. 185 **/ 186 virtual PVMFStatus GetCPMContentFilename(OSCL_wString& aFileName) 187 { 188 OSCL_UNUSED_ARG(aFileName); 189 return PVMFErrNotSupported; 190 } 191 192 /** 193 * Method to cancel an ongoing asynchronous command. 194 * This will attempt to interrupt the command and complete it 195 * as soon as possible. 196 * 197 * @param [in] The assigned plugin session ID to use for this request 198 * @param [in] The command ID of the command to cancel. 199 * @param [in] Optional context data. 200 * 201 * @returns A unique command id for asynchronous completion. 202 */ 203 virtual PVMFCommandId CancelCommand(PVMFSessionId, PVMFCommandId, const OsclAny* aContext = NULL) 204 { 205 OSCL_UNUSED_ARG(aContext); 206 return PVMFErrNotSupported; 207 } 208 209 /** 210 * Method to cancel all ongoing asynchronous commands. 211 * This will attempt to interrupt the command and complete it 212 * as soon as possible. 213 * 214 * @param [in] The assigned plugin session ID to use for this request 215 * @param [in] The command ID of the command to cancel. 216 * @param [in] Optional context data. 217 * 218 * @returns A unique command id for asynchronous completion. 219 */ 220 virtual PVMFCommandId CancelAllCommands(PVMFSessionId, const OsclAny* aContext = NULL) 221 { 222 OSCL_UNUSED_ARG(aContext); 223 return PVMFErrNotSupported; 224 } 225 226 protected: 227 PVMFCPMPluginInterface(int32 aSessionReserve = 228 PVMF_CPMPLUGIN_DEFAULT_SESSION_RESERVE) 229 { 230 iSessions.reserve(aSessionReserve); 231 iLoggedOn = false; 232 } 233 234 /** 235 * Establishes the usage thread context for the plug-in. 236 * The plug-in should do any thread-context sensitive initialization 237 * in this call. 238 **/ 239 virtual void ThreadLogon() = 0; 240 241 /** 242 * Exits the usage thread context for the plug-in. 243 * The plug-in should do any thread-context sensitive cleanup 244 * in this call. 245 **/ 246 virtual void ThreadLogoff() = 0; 247 248 Oscl_Vector<PVMFCPMPluginSession, OsclMemAllocator> iSessions; 249 bool iLoggedOn; 250 251 virtual void ReportCmdCompleteEvent(PVMFSessionId s, 252 PVMFCmdResp &resp) 253 { 254 for (uint32 i = 0; i < iSessions.size(); i++) 255 { 256 if (iSessions[i].iId == s) 257 { 258 iSessions[i].iCmdStatusObserver->CPMPluginCommandCompleted(resp); 259 break; 260 } 261 } 262 } 263 }; 264 265 /** 266 * Content Policy Manager Plugin Factory interface 267 */ 268 class PVMFCPMPluginFactory 269 { 270 public: 271 virtual PVMFCPMPluginInterface* CreateCPMPlugin() = 0; 272 virtual void DestroyCPMPlugin(PVMFCPMPluginInterface*) = 0; 273 virtual ~PVMFCPMPluginFactory() {} 274 }; 275 276 /** 277 * Content Policy Manager Plugin Registry Populator interface for use 278 * with dynamic loading. 279 */ 280 class OSCL_String; 281 class PVMFCPMPluginRegistryPopulator 282 { 283 public: 284 virtual ~PVMFCPMPluginRegistryPopulator() {} 285 /* 286 ** GetFactoryAndMimeString. Called by CPM framework to retrieve the plugin factory and 287 ** plugin mimestring. Note this will be called twice-- when creating the plugin and 288 ** again when destroying the plugin. 289 ** 290 ** @param (out) aMimestring: the plugin mimestring 291 ** @return : factory pointer. 292 */ 293 virtual PVMFCPMPluginFactory* GetFactoryAndMimeString(OSCL_String& aMimestring) = 0; 294 /* 295 ** ReleaseFactory. Called by CPM framework to indicate that the the plugin factory 296 ** retrieved by prior calls to GetFactoryAndMimeString is no longer needed. 297 */ 298 virtual void ReleaseFactory() = 0; 299 }; 300 301 #define PVMF_CPM_PLUGIN_REGISTRY_POPULATOR_UUID OsclUuid(0x8c988150,0x9b1b,0x11dd,0xad,0x8b,0x08,0x00,0x20,0x0c,0x9a,0x66) 302 303 #endif //PVMF_CPMPLUGIN_INTERFACE_H_INCLUDED 304 305
