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 * ============================================================================== 20 * Name : pvmf_recognizer_registry.h 21 * Part of : 22 * Interface : 23 * Description : Interface class with static methods for PVMF recognizer registry 24 * Version : (see RELEASE field in copyright header above) 25 * 26 * ============================================================================== 27 */ 28 29 #ifndef PVMF_RECOGNIZER_REGISTRY_H_INCLUDED 30 #define PVMF_RECOGNIZER_REGISTRY_H_INCLUDED 31 32 #ifndef OSCL_BASE_H_INCLUDED 33 #include "oscl_base.h" 34 #endif 35 36 #ifndef OSCL_VECTOR_H_INCLUDED 37 #include "oscl_vector.h" 38 #endif 39 40 #ifndef PVMF_RETURN_CODES_H_INCLUDED 41 #include "pvmf_return_codes.h" 42 #endif 43 44 #ifndef OSCL_STRING_H_INCLUDED 45 #include "oscl_string.h" 46 #endif 47 48 #ifndef PVMF_FORMAT_TYPE_H_INCLUDED 49 #include "pvmf_format_type.h" 50 #endif 51 52 #ifndef PVMF_RECOGNIZER_TYPES_H_INCLUDED 53 #include "pvmf_recognizer_types.h" 54 #endif 55 56 #ifndef PVMF_RECOGNIZER_PLUGIN_H_INCLUDED 57 #include "pvmf_recognizer_plugin.h" 58 #endif 59 60 #ifndef PVMI_DATASTREAMUSER_INTERFACE_H_INCLUDED 61 #include "pvmi_datastreamuser_interface.h" 62 #endif 63 64 65 /** 66 * A class of static methods that provides the interface to the PVMF recognizer registry.. 67 * With these static methods, the recognizer registry can be initialized and shutdown, recognizer 68 * plug-ins can be registered and unregistered, and format of a content can be recognized. 69 **/ 70 class PVMFRecognizerRegistry 71 { 72 public: 73 /** 74 * This static method initializes the recognizer registry for use. This method must be called once 75 * and succeed before calling any other methods from PVMFRecognizerRegistry. 76 * 77 * @exception This method can leave with one of the following error codes 78 * OsclErrNoMemory if memory cannot be allocated for the registry implementation 79 * @returns A PVMF status code to report result of method 80 **/ 81 OSCL_IMPORT_REF static PVMFStatus Init(); 82 83 /** 84 * This static methods shuts down and cleans up the recognizer registry. This method must be called once 85 * after there is no more use for the recognizer registry to properly release the memory allocated for the 86 * registry 87 **/ 88 OSCL_IMPORT_REF static void Cleanup(); 89 90 /** 91 * This static method adds the specified recognizer plug-in factory to the list of available recognizers. 92 * The passed-in plug-in factory would be used to create and destroy the recognizer plug-in in the Recognize() methods. 93 * The passed-in plug-in factory reference must be valid until it is removed from the list by the RemovePlugin() method. 94 * 95 * @param aPluginFactory 96 * A reference to a recognizer plug-in factory to add to the list of registered recognizers 97 * 98 * @exception This method can leave with one of the following error codes 99 * OsclErrNoMemory if memory cannot be allocated for vector holding the plug-in factory pointers 100 * @returns A PVMF status code to report result of method 101 **/ 102 OSCL_IMPORT_REF static PVMFStatus RegisterPlugin(PVMFRecognizerPluginFactory& aPluginFactory); 103 104 /** 105 * This static method removes the specified recognizer plug-in factory from the list of available recognizers. 106 * The passed-in plug-in factory must have been added before with RegisterPlugin() for this method to succeed. 107 * After the plug-in factory is successfully removed, the factory instance can be deleted. 108 * 109 * @param aPluginFactory 110 * A reference to a recognizer plug-in factory to remove from the list of registered recognizers 111 * 112 * @returns A PVMF status code to report result of method 113 **/ 114 OSCL_IMPORT_REF static PVMFStatus RemovePlugin(PVMFRecognizerPluginFactory& aPluginFactory); 115 116 /** 117 * This static method creates a recognition session with the recognizer framework. 118 * 119 * @param aSessionId 120 * A reference to a PVMFSessionId which will be set to the session's unique identifier when this method 121 * completes successfully. 122 * @param aCmdHandler 123 * A reference to a PVMFRecognizerCommmandHandler which will receive asynchronous command completion notification. 124 * 125 * @returns A PVMF status code to report result of method 126 **/ 127 OSCL_IMPORT_REF static PVMFStatus OpenSession(PVMFSessionId& aSessionId, PVMFRecognizerCommmandHandler& aCmdHandler); 128 129 /** 130 * This static method shuts down a recognition session with the recognizer framework. 131 * 132 * @param aSessionId 133 * The unique identifier of the session to close 134 * 135 * @returns A PVMF status code to report result of method 136 **/ 137 OSCL_IMPORT_REF static PVMFStatus CloseSession(PVMFSessionId aSessionId); 138 139 /** 140 * This static method asynchronously determines the format of the specified content using the currently registered 141 * recognizer plug-ins. When the recognizer request completes, the user would be notified via the PVMFRecognizerCommandHandler 142 * callback handler set when opening the session. 143 * 144 * @param aSessionId 145 * The unique identifier for the recognizer session 146 * @param aSourceDataStreamFactory 147 * A reference to a PVMFDataStreamFactory representing the content to recognize 148 * @param aFormatHintList 149 * An optional input parameter expressed as a list of MIME string which provides a priori hint for the format 150 * of the content specified by aSourceDataStreamFactory. 151 * @param aRecognizerResult 152 * An output parameter which is a reference to a vector of PVMFRecognizerResult that will contain the recognition 153 * result if the Recognize() method succeeds. 154 * @param aCmdContext 155 * Optional pointer to opaque data that will be returned in the command completion response 156 * @param aTimeout 157 * Optional timeout value for the recognition request. If the recognition operation takes more time than the timeout 158 * value, the operation will be cancelled with PVMFErrTimeout status code. If the timeout value is set to 0, the 159 * recognition operation will go to completion. 160 * 161 * @exception This method can leave with one of the following error codes 162 * OsclErrNoMemory if memory cannot allocated to process this request 163 * OsclErrArgument if one or more of the passed-in parameters is invalid 164 * 165 * @returns A PVMF command ID for the recognize request 166 **/ 167 OSCL_IMPORT_REF static PVMFCommandId Recognize(PVMFSessionId aSessionId, PVMFDataStreamFactory& aSourceDataStreamFactory, PVMFRecognizerMIMEStringList* aFormatHintList, 168 Oscl_Vector<PVMFRecognizerResult, OsclMemAllocator>& aRecognizerResult, OsclAny* aCmdContext = NULL, uint32 aTimeout = 0); 169 170 /** 171 * This static method cancels a previously issued asynchronous request that hasn't completed yet. 172 * 173 * @param aSessionId 174 * The unique identifier for the recognizer session 175 * @param aCommandToCancelId 176 * Unique identifier for the asynchronous request to cancel. 177 * @param aCmdContext 178 * Optional pointer to opaque data that will be returned in the command completion response 179 * 180 * @exception This method can leave with one of the following error codes 181 * OsclErrNoMemory if memory cannot allocated to process this request 182 * OsclErrArgument if one or more of the passed-in parameters is invalid 183 * 184 * @returns A PVMF command ID for the cancel request 185 **/ 186 OSCL_IMPORT_REF static PVMFCommandId CancelCommand(PVMFSessionId aSessionId, PVMFCommandId aCommandToCancelId, OsclAny* aCmdContext = NULL); 187 }; 188 189 #endif // PVMF_RECOGNIZER_REGISTRY_H_INCLUDED 190 191 192 193 194
