nodes/common/include/pvmf_meta_data_extension.h - platform/external/opencore - Git at Google

 /* ------------------------------------------------------------------
  * Copyright (C) 2008 PacketVideo
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
  * express or implied.
  * See the License for the specific language governing permissions
  * and limitations under the License.
  * -------------------------------------------------------------------
  */
 /**
  * @file pvmf_meta_data_extension.h
  * @brief Extension interface to retrieve metadata
  */

 #ifndef PVMF_META_DATA_EXTENSION_H_INCLUDED
 #define PVMF_META_DATA_EXTENSION_H_INCLUDED

 #ifndef OSCL_BASE_H_INCLUDED
 #include "oscl_base.h"
 #endif
 #ifndef PV_INTERFACE_H
 #include "pv_interface.h"
 #endif
 #ifndef PV_UUID_H_INCLUDED
 #include "pv_uuid.h"
 #endif
 #ifndef PVMF_FORMAT_TYPE_H_INCLUDED
 #include "pvmf_event_handling.h"
 #endif
 #ifndef PVMF_META_DATA_TYPES_H_INCLUDED
 #include "pvmf_meta_data_types.h"
 #endif
 #ifndef PVMI_KVP_H_INCLUDED
 #include "pvmi_kvp.h"
 #endif

 #define PVMF_META_DATA_EXTENSION_INTERFACE_MIMETYPE "pvxxx/pvmf/pvmfmetadataextensioninterface"

 // UUID for the extension interface
 #define KPVMFMetadataExtensionUuid  PVUuid(0x7DBD6D8D,0xB4CC,0x4887,0xB1,0x0B,0x7E,0xE6,0x48,0x47,0xB2,0x05)

 /**
  * PVMFMetadataExtensionInterface specifies the extension interface for metadata retrieval
  */
 class PVMFMetadataExtensionInterface : public PVInterface
 {
     public:
         /**
          * Synchronous method to return the number of metadata keys for the specified query key string
          *
          * @param aQueryKeyString A NULL terminated character string specifying a subset of metadata keys to count.
          *                        If the string is NULL, total number of all keys will be returned
          *
          * @returns The number of metadata keys
          **/
         virtual uint32 GetNumMetadataKeys(char* aQueryKeyString = NULL) = 0;

         /**
          * Synchronous method to return the number of metadata values for the specified list of key strings
          *
          * @param aKeyList A reference to a metadata key list to specifying the values of interest to count
          *
          * @returns The number of metadata values based on the provided key list
          **/
         virtual uint32 GetNumMetadataValues(PVMFMetadataList& aKeyList) = 0;

         /**
          * Asynchronous method to retrieve a list of metadata keys. The subset of all available keys in the node can
          * be specified by providing a combination of query key string, starting index, and maximum number of keys to retrieve
          *
          * @param aSessionId The assigned node session ID to use for this request
          * @param aKeyList A reference to a metadata key list to add the metadata keys
          * @param aStartingKeyIndex Index into the node's total key list that corresponds to the first key entry to retrieve
          * @param aMaxKeyEntries The maximum number of key entries to add to aKeyList. If there is no maximum, set to -1.
          * @param aQueryKeyString Optional NULL terminated character string to select a subset of keys
          * @param aContext Optional opaque data to be passed back to user with the command response
          *
          * @returns A unique command ID for asynchronous completion
          **/
         virtual PVMFCommandId GetNodeMetadataKeys(PVMFSessionId aSessionId,
                 PVMFMetadataList& aKeyList,
                 uint32 aStartingKeyIndex,
                 int32 aMaxKeyEntries = -1,
                 char* aQueryKeyString = NULL,
                 const OsclAny* aContextData = NULL) = 0;

         /**
          * Asynchronous method to retrieve a list of metadata values. The subset of all available values in the node can
          * be specified by providing a combination of key list, starting index, and maximum number of values to retrieve
          *
          * @param aSessionId The assigned node session ID to use for this request
          * @param aKeyList A reference to a metadata key list specifying the metadata values to retrieve
          * @param aValueList A reference to a metadata value list to add the metadata values
          * @param aStartingValueIndex Index into the node's value list specified by the key list that corresponds to the first value entry to retrieve
          * @param aMaxValueEntries The maximum number of value entries to add to aValueList. If there is no maximum, set to -1.
          * @param aContext Optional opaque data to be passed back to user with the command response
          *
          * @returns A unique command ID for asynchronous completion
          **/
         virtual PVMFCommandId GetNodeMetadataValues(PVMFSessionId aSessionId,
                 PVMFMetadataList& aKeyList,
                 Oscl_Vector<PvmiKvp, OsclMemAllocator>& aValueList,
                 uint32 aStartingValueIndex,
                 int32 aMaxValueEntries = -1,
                 const OsclAny* aContextData = NULL) = 0;

         /**
          * Synchronous method to free up the specified range of metadata keys in the list. It is assumed that caller of this function
          * knows that start and end indices should correspond to metadata keys returned by this particular instance of the
          * metadata extension interface using GetNodeMetadataKeys().
          *
          * @param aKeyList A reference to a metadata key list to free the key entries
          * @param aStartingKeyIndex Index into aKeyList that corresponds to the first key entry to release
          * @param aEndKeyIndex Index into aKeyList that corresponds to the last key entry to release
          *
          * @returns PVMFSuccess if the release of specified keys succeeded. PVMFErrArgument if indices are invalid or the list is empty.
          *          PVMFFailure otherwise.
          **/
         virtual PVMFStatus ReleaseNodeMetadataKeys(PVMFMetadataList& aKeyList,
                 uint32 aStartingKeyIndex,
                 uint32 aEndKeyIndex) = 0;

         /**
          * Synchronous method to free up the specified range of metadata values in the list. It is assumed that caller of this function
          * knows that start and end indices should correspond to metadata values returned by this particular instance of the
          * metadata extension interface using GetNodeMetadataValues().
          *
          * @param aValueList A reference to a metadata value list to free the value entries
          * @param aStartingValueIndex Index into aValueList that corresponds to the first value entry to release
          * @param aEndValueIndex Index into aValueList that corresponds to the last value entry to release
          *
          * @returns PVMFSuccess if the release of specified values succeeded. PVMFErrArgument if indices are invalid or the list is empty.
          *          PVMFFailure otherwise.
          **/
         virtual PVMFStatus ReleaseNodeMetadataValues(Oscl_Vector<PvmiKvp, OsclMemAllocator>& aValueList,
                 uint32 aStartingValueIndex,
                 uint32 aEndValueIndex) = 0;

         // From PVInterface
         virtual void addRef() = 0;

         virtual void removeRef() = 0;

         virtual bool queryInterface(const PVUuid& uuid, PVInterface*& iface) = 0;
 };

 #endif // PVMF_META_DATA_EXTENSION_H_INCLUDED
	/* ------------------------------------------------------------------
	* Copyright (C) 2008 PacketVideo
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
	* express or implied.
	* See the License for the specific language governing permissions
	* and limitations under the License.
	* -------------------------------------------------------------------
	*/
	/**
	* @file pvmf_meta_data_extension.h
	* @brief Extension interface to retrieve metadata
	*/

	#ifndef PVMF_META_DATA_EXTENSION_H_INCLUDED
	#define PVMF_META_DATA_EXTENSION_H_INCLUDED

	#ifndef OSCL_BASE_H_INCLUDED
	#include "oscl_base.h"
	#endif
	#ifndef PV_INTERFACE_H
	#include "pv_interface.h"
	#endif
	#ifndef PV_UUID_H_INCLUDED
	#include "pv_uuid.h"
	#endif
	#ifndef PVMF_FORMAT_TYPE_H_INCLUDED
	#include "pvmf_event_handling.h"
	#endif
	#ifndef PVMF_META_DATA_TYPES_H_INCLUDED
	#include "pvmf_meta_data_types.h"
	#endif
	#ifndef PVMI_KVP_H_INCLUDED
	#include "pvmi_kvp.h"
	#endif

	#define PVMF_META_DATA_EXTENSION_INTERFACE_MIMETYPE "pvxxx/pvmf/pvmfmetadataextensioninterface"

	// UUID for the extension interface
	#define KPVMFMetadataExtensionUuid PVUuid(0x7DBD6D8D,0xB4CC,0x4887,0xB1,0x0B,0x7E,0xE6,0x48,0x47,0xB2,0x05)

	/**
	* PVMFMetadataExtensionInterface specifies the extension interface for metadata retrieval
	*/
	class PVMFMetadataExtensionInterface : public PVInterface
	{
	public:
	/**
	* Synchronous method to return the number of metadata keys for the specified query key string
	*
	* @param aQueryKeyString A NULL terminated character string specifying a subset of metadata keys to count.
	* If the string is NULL, total number of all keys will be returned
	*
	* @returns The number of metadata keys
	**/
	virtual uint32 GetNumMetadataKeys(char* aQueryKeyString = NULL) = 0;

	/**
	* Synchronous method to return the number of metadata values for the specified list of key strings
	*
	* @param aKeyList A reference to a metadata key list to specifying the values of interest to count
	*
	* @returns The number of metadata values based on the provided key list
	**/
	virtual uint32 GetNumMetadataValues(PVMFMetadataList& aKeyList) = 0;

	/**
	* Asynchronous method to retrieve a list of metadata keys. The subset of all available keys in the node can
	* be specified by providing a combination of query key string, starting index, and maximum number of keys to retrieve
	*
	* @param aSessionId The assigned node session ID to use for this request
	* @param aKeyList A reference to a metadata key list to add the metadata keys
	* @param aStartingKeyIndex Index into the node's total key list that corresponds to the first key entry to retrieve
	* @param aMaxKeyEntries The maximum number of key entries to add to aKeyList. If there is no maximum, set to -1.
	* @param aQueryKeyString Optional NULL terminated character string to select a subset of keys
	* @param aContext Optional opaque data to be passed back to user with the command response
	*
	* @returns A unique command ID for asynchronous completion
	**/
	virtual PVMFCommandId GetNodeMetadataKeys(PVMFSessionId aSessionId,
	PVMFMetadataList& aKeyList,
	uint32 aStartingKeyIndex,
	int32 aMaxKeyEntries = -1,
	char* aQueryKeyString = NULL,
	const OsclAny* aContextData = NULL) = 0;

	/**
	* Asynchronous method to retrieve a list of metadata values. The subset of all available values in the node can
	* be specified by providing a combination of key list, starting index, and maximum number of values to retrieve
	*
	* @param aSessionId The assigned node session ID to use for this request
	* @param aKeyList A reference to a metadata key list specifying the metadata values to retrieve
	* @param aValueList A reference to a metadata value list to add the metadata values
	* @param aStartingValueIndex Index into the node's value list specified by the key list that corresponds to the first value entry to retrieve
	* @param aMaxValueEntries The maximum number of value entries to add to aValueList. If there is no maximum, set to -1.
	* @param aContext Optional opaque data to be passed back to user with the command response
	*
	* @returns A unique command ID for asynchronous completion
	**/
	virtual PVMFCommandId GetNodeMetadataValues(PVMFSessionId aSessionId,
	PVMFMetadataList& aKeyList,
	Oscl_Vector<PvmiKvp, OsclMemAllocator>& aValueList,
	uint32 aStartingValueIndex,
	int32 aMaxValueEntries = -1,
	const OsclAny* aContextData = NULL) = 0;

	/**
	* Synchronous method to free up the specified range of metadata keys in the list. It is assumed that caller of this function
	* knows that start and end indices should correspond to metadata keys returned by this particular instance of the
	* metadata extension interface using GetNodeMetadataKeys().
	*
	* @param aKeyList A reference to a metadata key list to free the key entries
	* @param aStartingKeyIndex Index into aKeyList that corresponds to the first key entry to release
	* @param aEndKeyIndex Index into aKeyList that corresponds to the last key entry to release
	*
	* @returns PVMFSuccess if the release of specified keys succeeded. PVMFErrArgument if indices are invalid or the list is empty.
	* PVMFFailure otherwise.
	**/
	virtual PVMFStatus ReleaseNodeMetadataKeys(PVMFMetadataList& aKeyList,
	uint32 aStartingKeyIndex,
	uint32 aEndKeyIndex) = 0;

	/**
	* Synchronous method to free up the specified range of metadata values in the list. It is assumed that caller of this function
	* knows that start and end indices should correspond to metadata values returned by this particular instance of the
	* metadata extension interface using GetNodeMetadataValues().
	*
	* @param aValueList A reference to a metadata value list to free the value entries
	* @param aStartingValueIndex Index into aValueList that corresponds to the first value entry to release
	* @param aEndValueIndex Index into aValueList that corresponds to the last value entry to release
	*
	* @returns PVMFSuccess if the release of specified values succeeded. PVMFErrArgument if indices are invalid or the list is empty.
	* PVMFFailure otherwise.
	**/
	virtual PVMFStatus ReleaseNodeMetadataValues(Oscl_Vector<PvmiKvp, OsclMemAllocator>& aValueList,
	uint32 aStartingValueIndex,
	uint32 aEndValueIndex) = 0;

	// From PVInterface
	virtual void addRef() = 0;

	virtual void removeRef() = 0;

	virtual bool queryInterface(const PVUuid& uuid, PVInterface*& iface) = 0;
	};

	#endif // PVMF_META_DATA_EXTENSION_H_INCLUDED