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 F _ N O D E _ R E G I S T R Y
22
23// = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
24
25/*! \addtogroup pvmfnoderegistry PVMFNodeRegistry
26*
27* @{
28*/
29
30
31/*! \file pvmf_node_registry.h
32\brief This file contains the declarations for the node registry.
33*/
34
35#ifndef PVMF_NODE_REGSITRY_H_INCLUDED
36#define PVMF_NODE_REGSITRY_H_INCLUDED
37
38#include "pv_interface.h"
39#include "pv_uuid.h"
40#include "pvmf_event_handling.h"
41#include "oscl_vector.h"
42#include "pvmf_format_type.h"
43#include "oscl_string_containers.h"
44
45class PVMFNodeInterface;
46class PvmiMIOControl;
47
48
49/*
50** An abstract interface class containing a function
51** to do a synchronous interface query.
52** Each registered component must support this interface.
53*/
54typedef PVInterface PVMFSimpleQueryInterface ;
55
56
57/*
58** An abstract interface class containing methods
59** to create and release a PVMF node.
60*/
61class PVMFNodeCreationInterface
62{
63    public:
64        /** Virtual destructor
65        **   need to be defined to avoid compiler warnings
66        **/
67        virtual ~PVMFNodeCreationInterface() {}
68
69        /**
70        ** Create a node instance.  May throw an exception if
71        **  node creation fails due to out-of-memory condition or other error.
72        **
73        ** @param aParam optional opaque data to be passed to node constructor.
74        ** @return pointer to the node.
75        */
76        virtual PVMFNodeInterface* CreateNode(OsclAny* aParam = NULL) = 0;
77
78        /**
79        ** Relese a node instance previously created with CreateNode.
80        **
81        ** @param aNode (input): the node instance.
82        */
83        virtual void ReleaseNode(PVMFNodeInterface* aNode) = 0;
84};
85
86/*
87** An abstract interface class containing methods
88** to create and release a Media I/O component.
89*/
90class PVMFMediaIOCreationInterface
91{
92    public:
93        /** Virtual destructor
94        **   need to be defined to avoid compiler warnings
95        **/
96        virtual ~PVMFMediaIOCreationInterface() {}
97        /**
98        ** Create a Media I/O component instance.  May throw an exception if
99        **  creation fails due to out-of-memory condition or other error.
100        **
101        ** @param aParam: optional opaque data to pass the MIO constructor.
102        ** @return pointer to the component.
103        */
104        virtual PvmiMIOControl* CreateMediaIO(OsclAny*aParam = NULL) = 0;
105
106        /**
107        ** Relese a Media I/O component instance previously created with CreateMediaIO.
108        **
109        ** @param aMediaIO (input): the media I/O instance.
110        */
111        virtual void ReleaseMediaIO(PvmiMIOControl* aMediaIO) = 0;
112};
113
114
115
116/*
117** A class to encapsulate PVMF media format information.
118** The media format is a MIME string, such as audio/compressed/amr
119*/
120class PVMFComponentFormatType
121{
122    public:
123        OSCL_IMPORT_REF PVMFComponentFormatType(const char*aFmtStr);
124
125        PVMFComponentFormatType(const PVMFComponentFormatType& s)
126        {
127            iFormatType = s.iFormatType;
128            iFormatString = s.iFormatString;
129        }
130
131        OSCL_HeapString<OsclMemAllocator> iFormatString;
132        PVMFFormatType iFormatType;
133
134        OSCL_IMPORT_REF bool operator== (const PVMFComponentFormatType& src) const;
135
136};
137
138
139/*
140** A class to encapsulate PVMF media format pair information.
141** A format pair consists of an input format and an output format.
142*/
143class PVMFComponentFormatPairType
144{
145    public:
146        PVMFComponentFormatPairType(char* input
147                                    , char* output)
148                : iInputFormat(PVMFComponentFormatType(input))
149                , iOutputFormat(PVMFComponentFormatType(output))
150        {}
151        PVMFComponentFormatPairType(PVMFComponentFormatType& input
152                                    , PVMFComponentFormatType& output)
153                : iInputFormat(input)
154                , iOutputFormat(output)
155        {}
156
157        PVMFComponentFormatPairType(const PVMFComponentFormatPairType& s)
158                : iInputFormat(s.iInputFormat)
159                , iOutputFormat(s.iOutputFormat)
160        {}
161
162        PVMFComponentFormatType iInputFormat;
163        PVMFComponentFormatType iOutputFormat;
164};
165
166/*
167** Format list types.
168*/
169typedef Oscl_Vector<PVMFComponentFormatType, OsclMemAllocator> PVMFComponentFormatListType;
170typedef Oscl_Vector<PVMFComponentFormatPairType, OsclMemAllocator> PVMFComponentFormatPairListType;
171
172/*
173** A class containing information about the capability of a component.
174*/
175class PVMFComponentCapability
176{
177    public:
178        PVMFComponentCapability()
179        {}
180
181        PVMFComponentCapability(const PVMFComponentCapability& s)
182                : iInputFormatCapability(s.iInputFormatCapability)
183                , iOutputFormatCapability(s.iOutputFormatCapability)
184                , iInputOutputFormatCapability(s.iInputOutputFormatCapability)
185        {}
186
187        /**
188        ** Supported format information can be specified by lists of input
189        ** and/or output format, or a list of input/output format pairs.
190        */
191        void AddInputFormat(const char* fmt)
192        {
193            iInputFormatCapability.push_back(PVMFComponentFormatType(fmt));
194        }
195        void AddOutputFormat(char* fmt)
196        {
197            iOutputFormatCapability.push_back(PVMFComponentFormatType(fmt));
198        }
199        void AddFormatPair(char* infmt, char* outfmt)
200        {
201            iInputOutputFormatCapability.push_back(PVMFComponentFormatPairType(infmt, outfmt));
202        }
203
204        Oscl_Vector<PVMFComponentFormatType, OsclMemAllocator> iInputFormatCapability;
205        Oscl_Vector<PVMFComponentFormatType, OsclMemAllocator> iOutputFormatCapability;
206        Oscl_Vector<PVMFComponentFormatPairType, OsclMemAllocator> iInputOutputFormatCapability;
207};
208
209/*
210** Base class for component registration info.
211*/
212class PVMFComponentRegistrationInfo
213{
214    public:
215        PVMFComponentRegistrationInfo()
216        {
217            iHasHardwareAssist = false;
218            iQueryInterface = NULL;
219        }
220
221        PVMFComponentRegistrationInfo(const PVMFComponentRegistrationInfo& a)
222                : iUuid(a.iUuid)
223                , iMediaCategory(a.iMediaCategory)
224                , iComponentType(a.iComponentType)
225                , iCapability(a.iCapability)
226                , iHasHardwareAssist(a.iHasHardwareAssist)
227                , iQueryInterface(a.iQueryInterface)
228        {
229        }
230
231        PVMFComponentRegistrationInfo(PVUuid& aUuid
232                                      , char* aMediaCategory
233                                      , char* aComponentType
234                                      , PVMFComponentCapability& aCapability
235                                      , bool aHasHardwareAssist
236                                      , PVMFSimpleQueryInterface* aQueryInterface)
237                : iCapability(aCapability)
238        {
239            OSCL_UNUSED_ARG(aUuid);
240
241            if (aMediaCategory)
242                iMediaCategory = aMediaCategory;
243            if (aComponentType)
244                iComponentType = aComponentType;
245            iHasHardwareAssist = aHasHardwareAssist;
246            iQueryInterface = aQueryInterface;
247        }
248
249
250        /**
251        ** Unique identifier
252        */
253        PVUuid iUuid;
254
255        /**
256        ** Media category, e.g. "audio", "video", "text", "image", "multi"
257        */
258        OSCL_HeapString<OsclMemAllocator> iMediaCategory;
259
260        /**
261        ** Hierarchical component type string, e.g. "source/capture", "source/file",
262        **   "source/media_io",
263        **   "file_parser/mpeg4", "codec/audio/aac", "codec/video/h263",
264        **   "sink/file", "sink/render", "sink/media_io"
265        */
266        OSCL_HeapString<OsclMemAllocator> iComponentType;
267
268        /**
269        ** Component capability information
270        */
271        PVMFComponentCapability iCapability;
272
273        /**
274        ** Hardware assist flag.  Set to true if component may have hardware assist;
275        **   set to false if component is pure software.
276        */
277        bool iHasHardwareAssist;
278
279        /**
280        ** Optional pointer to a simple query interface implementation for the component.
281        */
282        PVMFSimpleQueryInterface* iQueryInterface;
283
284};
285
286/*
287** A class containing all data required to register a node.
288** The node may be registered with either an implemenation instance,
289** or a creation interface instance.
290*/
291class PVMFNodeRegistrationInfo: public PVMFComponentRegistrationInfo
292{
293    public:
294        PVMFNodeRegistrationInfo()
295        {
296            iNodeInstance = NULL;
297            iNodeCreationInterface = NULL;
298        }
299        PVMFNodeRegistrationInfo(const PVMFNodeRegistrationInfo& a)
300                : PVMFComponentRegistrationInfo(a)
301                , iNodeCreationInterface(a.iNodeCreationInterface)
302                , iNodeInstance(a.iNodeInstance)
303        {}
304
305        PVMFNodeRegistrationInfo(PVUuid& aUuid
306                                 , char* aMediaCategory
307                                 , char* aNodeType
308                                 , PVMFComponentCapability& aCapability
309                                 , bool aHasHardwareAssist
310                                 , PVMFSimpleQueryInterface* aQueryInterface
311                                 , PVMFNodeInterface& aNodeInstance)
312                : PVMFComponentRegistrationInfo(aUuid, aMediaCategory, aNodeType, aCapability, aHasHardwareAssist, aQueryInterface)
313                , iNodeInstance(&aNodeInstance)
314        {
315            iNodeCreationInterface = NULL;
316        }
317
318        PVMFNodeRegistrationInfo(PVUuid& aUuid
319                                 , char* aMediaCategory
320                                 , char* aNodeType
321                                 , PVMFComponentCapability& aCapability
322                                 , bool aHasHardwareAssist
323                                 , PVMFSimpleQueryInterface* aQueryInterface
324                                 , PVMFNodeCreationInterface& aNodeCreation)
325                : PVMFComponentRegistrationInfo(aUuid, aMediaCategory, aNodeType, aCapability, aHasHardwareAssist, aQueryInterface)
326                , iNodeCreationInterface(&aNodeCreation)
327        {
328            iNodeInstance = NULL;
329        }
330
331
332        /**
333        ** Optional pointer to node creation implementation.  Nodes must register
334        ** with either an instance pointer, or else a creation interface implementation.
335        */
336        PVMFNodeCreationInterface* iNodeCreationInterface;
337        /**
338        ** Optional pointer to node instance.  Nodes must register
339        ** with either an instance pointer, or else a creation interface implementation.
340        */
341        PVMFNodeInterface* iNodeInstance;
342};
343
344
345/*
346** A class containing all data required to register a media I/O component.
347** The component may be registered with either an implemenation instance,
348** or a creation interface instance.
349*/
350class PVMFMediaIORegistrationInfo: public PVMFComponentRegistrationInfo
351{
352    public:
353        PVMFMediaIORegistrationInfo()
354        {
355            iMediaIOCreationInterface = NULL;
356            iMediaIOInstance = NULL;
357        }
358        PVMFMediaIORegistrationInfo(const PVMFMediaIORegistrationInfo& a)
359                : PVMFComponentRegistrationInfo(a)
360                , iMediaIOCreationInterface(a.iMediaIOCreationInterface)
361                , iMediaIOInstance(a.iMediaIOInstance)
362        {}
363
364        PVMFMediaIORegistrationInfo(PVUuid& aUuid
365                                    , char* aMediaCategory
366                                    , char* aMediaIOType
367                                    , PVMFComponentCapability& aCapability
368                                    , bool aHasHardwareAssist
369                                    , PVMFSimpleQueryInterface* aQueryInterface
370                                    , PvmiMIOControl& aMediaIOInstance)
371                : PVMFComponentRegistrationInfo(aUuid, aMediaCategory, aMediaIOType, aCapability, aHasHardwareAssist, aQueryInterface)
372                , iMediaIOInstance(&aMediaIOInstance)
373        {
374            iMediaIOCreationInterface = NULL;
375        }
376
377        PVMFMediaIORegistrationInfo(PVUuid& aUuid
378                                    , char* aMediaCategory
379                                    , char* aMediaIOType
380                                    , PVMFComponentCapability& aCapability
381                                    , bool aHasHardwareAssist
382                                    , PVMFSimpleQueryInterface* aQueryInterface
383                                    , PVMFMediaIOCreationInterface& aMediaIOCreation)
384                : PVMFComponentRegistrationInfo(aUuid, aMediaCategory, aMediaIOType, aCapability, aHasHardwareAssist, aQueryInterface)
385                , iMediaIOCreationInterface(&aMediaIOCreation)
386        {
387            iMediaIOInstance = NULL;
388        }
389
390
391        /**
392        ** Optional pointer to Media I/O creation implementation.  Components must register
393        ** with either an instance pointer, or else a creation interface implementation.
394        */
395        PVMFMediaIOCreationInterface* iMediaIOCreationInterface;
396        /**
397        ** Optional pointer to Media I/O control instance.  Components must register
398        ** with either an instance pointer, or else a creation interface implementation.
399        */
400        PvmiMIOControl* iMediaIOInstance;
401};
402
403
404typedef uint32 PVMFRegistryIdType;
405
406/*
407** Base class for component registry entries.
408*/
409class PVMFComponentRegistryEntry
410{
411    public:
412        //match category, type, and formats.
413        bool Match(char* aMediaCategory = NULL
414                                          , char* aComponentType = NULL
415                                                                   , char* aInputFormat = NULL
416                                                                                          , char* aOutputFormat = NULL);
417
418        //match individual items.
419        bool MatchMediaCategory(char* m);
420        bool MatchComponentType(char* m);
421        bool MatchFormat(char* in, char* out);
422        bool MatchUuid(PVUuid&);
423
424    protected:
425
426        PVMFComponentRegistryEntry(PVMFComponentRegistrationInfo &aInfo
427                                   , PVMFRegistryIdType aId)
428                : iInfo(aInfo)
429                , iId(aId)
430        {}
431
432        ~PVMFComponentRegistryEntry();
433
434        //The component registration info.
435        PVMFComponentRegistrationInfo& iInfo;
436
437        //Component ID assigned during registration.
438        PVMFRegistryIdType iId;
439
440    private:
441        static bool matchFormat(PVMFComponentFormatType&, PVMFComponentFormatListType&);
442        static bool matchFormatPair(PVMFComponentFormatType&, PVMFComponentFormatType&, PVMFComponentFormatPairListType&);
443        static bool matchInputFormat(PVMFComponentFormatType&, PVMFComponentFormatPairListType&);
444        static bool matchOutputFormat(PVMFComponentFormatType&, PVMFComponentFormatPairListType&);
445
446};
447
448
449/*
450** A class defining the node registry entries.
451*/
452class PVMFNodeRegistryEntry: public PVMFComponentRegistryEntry
453{
454    public:
455        /*
456        ** Methods to create and release a node instance
457        ** for this entry.
458        ** The Get and Release calls must be balanced.
459        ** @param aParam: optional param to pass to CreateNode.
460        */
461        OSCL_IMPORT_REF PVMFNodeInterface* GetNodeInstance(OsclAny*aParam = NULL);
462        OSCL_IMPORT_REF void ReleaseNodeInstance(PVMFNodeInterface*);
463
464        /**
465        ** For accessing the registration data
466        */
467        const PVMFNodeRegistrationInfo& Info()const
468        {
469            return iInfo;
470        }
471
472    private:
473        friend class PVMFNodeRegistry;
474
475        PVMFNodeRegistryEntry(PVMFNodeRegistrationInfo& aInfo
476                              , PVMFRegistryIdType aId)
477                : PVMFComponentRegistryEntry(iInfo, aId)
478                , iInfo(aInfo)
479        {}
480
481        PVMFNodeRegistrationInfo iInfo;
482
483};
484
485/*
486** A class defining the Media I/O registry entries.
487*/
488class PVMFMediaIORegistryEntry: public PVMFComponentRegistryEntry
489{
490    public:
491        /*
492        ** Methods to create and release a Media I/O instance
493        ** for this entry.
494        ** The Get and Release calls must be balanced.
495        ** @param: optional param to pass to CreateMediaIO
496        */
497        OSCL_IMPORT_REF PvmiMIOControl* GetMediaIOInstance(OsclAny*aParam = NULL);
498        OSCL_IMPORT_REF void ReleaseMediaIOInstance(PvmiMIOControl*);
499
500        /**
501        ** For accessing the registration data
502        */
503        const PVMFMediaIORegistrationInfo& Info()const
504        {
505            return iInfo;
506        }
507
508    private:
509        friend class PVMFMediaIORegistry;
510
511        PVMFMediaIORegistryEntry(PVMFMediaIORegistrationInfo& aInfo
512                                 , PVMFRegistryIdType aId)
513                : PVMFComponentRegistryEntry(iInfo, aId)
514                , iInfo(aInfo)
515        {}
516
517        PVMFMediaIORegistrationInfo iInfo;
518
519};
520
521
522/*
523** The node registry
524*/
525
526
527typedef Oscl_Vector<PVMFNodeRegistryEntry*, OsclMemAllocator> PVMFNodeList;
528
529class PVMFNodeRegistry
530{
531    public:
532        OSCL_IMPORT_REF PVMFNodeRegistry();
533        OSCL_IMPORT_REF ~PVMFNodeRegistry();
534
535        /*
536        ** Method to register a node.
537        ** @param: the node entry.
538        ** @return: the registry ID.
539        */
540        OSCL_IMPORT_REF PVMFRegistryIdType RegisterNode(PVMFNodeRegistrationInfo &entry);
541
542        /*
543        ** Method to unregister a node.
544        ** @param: registry ID of the node
545        */
546        OSCL_IMPORT_REF void UnregisterNode(PVMFRegistryIdType);
547
548        /*
549        ** Method to unregister all nodes.
550        */
551        OSCL_IMPORT_REF void Clear();
552
553        /*
554        ** Method to find all entries that match a given criteria.
555        ** Input parameters are used to filter the search.  Any
556        ** input that is NULL will be ignored.
557        ** @param aMatchList(output): list of components that satisfy the query.
558        ** @param aMediaCategory(input): media category string
559        ** @param aComponentType(input): media component type string
560        ** @param aInputFormat(input): input format
561        ** @param aOutputFormat(input): output format
562        */
563        OSCL_IMPORT_REF void Find(PVMFNodeList& aMatchList
564                                  , char* aMediaCategory = NULL
565                                                           , char* aComponentType = NULL
566                                                                                    , char* aInputFormat = NULL
567                                                                                                           , char* aOutputFormat = NULL);
568
569        OSCL_IMPORT_REF void Find(PVMFNodeList& aMatchList
570                                  , PVUuid& aUuid);
571
572        /*
573        ** For direct access to the node list
574        */
575        PVMFNodeList& NodeList()
576        {
577            return iNodeList;
578        }
579
580    private:
581        PVMFRegistryIdType iIdCounter;
582
583        PVMFNodeList iNodeList;
584
585};
586
587/*
588** The media I/O registry
589*/
590
591typedef Oscl_Vector<PVMFMediaIORegistryEntry*, OsclMemAllocator> PVMFMediaIOList;
592
593class PVMFMediaIORegistry
594{
595    public:
596        OSCL_IMPORT_REF PVMFMediaIORegistry();
597        OSCL_IMPORT_REF ~PVMFMediaIORegistry();
598
599        /*
600        ** Method to register a Media I/O component
601        ** @param: the media I/O component entry.
602        ** @return: the registry ID.
603        */
604        OSCL_IMPORT_REF PVMFRegistryIdType RegisterMediaIO(PVMFMediaIORegistrationInfo& entry);
605
606        /*
607        ** Method to unregister a Media I/O component.
608        ** @param: registry ID of the component
609        */
610        OSCL_IMPORT_REF void UnregisterMediaIO(PVMFRegistryIdType aId);
611
612        /*
613        ** Method to unregister all components.
614        */
615        OSCL_IMPORT_REF void Clear();
616
617        /*
618        ** Method to find all entries that match a given criteria.
619        ** Input parameters are used to filter the search.  Any
620        ** input that is NULL will be ignored.
621        ** @param aMatchList(output): list of components that satisfy the query.
622        ** @param aMediaCategory(input): media category string
623        ** @param aComponentType(input): media component type string
624        ** @param aInputFormat(input): input format
625        ** @param aOutputFormat(input): output format
626        */
627        OSCL_IMPORT_REF void Find(PVMFMediaIOList& aMatchList
628                                  , char* aMediaCategory = NULL
629                                                           , char* aComponentType = NULL
630                                                                                    , char* aInputFormat = NULL
631                                                                                                           , char* aOutputFormat = NULL);
632
633        OSCL_IMPORT_REF void Find(PVMFMediaIOList& aMatchList
634                                  , PVUuid& aUuid);
635
636        /*
637        ** For direct access to the component list
638        */
639        PVMFMediaIOList& MediaIOList()
640        {
641            return iMediaIOList;
642        }
643
644    private:
645        PVMFRegistryIdType iIdCounter;
646
647        PVMFMediaIOList iMediaIOList;
648
649};
650
651#endif //PVMF_NODE_REGSITRY_H_INCLUDED
652
653
654
655
656