rom/utility/findnamedobject.c

   1 /*
   2     Copyright © 1995-2001, The AROS Development Team. All rights reserved.
   3     $Id$
   4
   5     Desc: FindNamedObject() - find a NamedObject in a given NameSpace.
   6     Lang: english
   7 */
   8 #include <proto/exec.h>
   9 #include "intern.h"
  10
  11 /*****************************************************************************
  12
  13     NAME */
  14 #include <utility/name.h>
  15 #include <proto/utility.h>
  16
  17         AROS_LH3(struct NamedObject *, FindNamedObject,
  18
  19 /*  SYNOPSIS */
  20         AROS_LHA(struct NamedObject *, nameSpace, A0),
  21         AROS_LHA(CONST_STRPTR        , name, A1),
  22         AROS_LHA(struct NamedObject *, lastObject, A2),
  23
  24 /*  LOCATION */
  25         struct UtilityBase *, UtilityBase, 40, Utility)
  26
  27 /*  FUNCTION
  28         This function will search through a given NameSpace, or the
  29         system global NameSpace to find a NamedObject with the name
  30         requested. Optionally you can have the search start from a
  31         specific NamedObject. This way you can look for each occurence
  32         of a specifically named NamedObject in a NameSpace that allows
  33         for duplicates.
  34
  35     INPUTS
  36         nameSpace   -   The NameSpace to search through. If NULL will use
  37                         the system default NameSpace.
  38         name        -   The name of the object to search for. If NULL,
  39                         any and all NamedObjects will be matched.
  40         lastObject  -   The (optional) last NamedObject to start the search
  41                         from.
  42
  43     RESULT
  44         If a NamedObject with the name supplied exists, it will be returned.
  45         Otherwise will return NULL.
  46
  47         When you have finised with this NamedObject, you should call
  48         ReleaseNamedObject( NamedObject ).
  49
  50     NOTES
  51         If you are going to use a returned NamedObject to be the starting
  52         point for another search you must call ReleaseNamedObject() AFTER
  53         searching, as the ReleaseNamedObject() call can cause the NamedObject
  54         to be freed, leaving you with an invalid pointer.
  55
  56     EXAMPLE
  57
  58     BUGS
  59
  60     SEE ALSO
  61         ReleaseNamedObject()
  62
  63     INTERNALS
  64         Could we implement named objects with hash chains perhaps?
  65         Possibly not as then NextObject handling would be quite tricky.
  66
  67     HISTORY
  68         29-10-95    digulla automatically created from
  69                             utility_lib.fd and clib/utility_protos.h
  70         11-08-96    iaint   Wrote based on AmigaOS 3.0 function.
  71         07-02-97    iaint   Corrected handling of NULL name.
  72
  73 *****************************************************************************/
  74 {
  75     AROS_LIBFUNC_INIT
  76
  77     struct NamedObject      *foundObj = NULL;
  78     struct IntNamedObject   *no;
  79     struct Node             *StartObj;
  80     struct NameSpace        *ns;
  81
  82     ns = GetNameSpace( nameSpace, UtilityBase);
  83     ObtainSemaphore( &ns->ns_Lock );
  84
  85     /* It is a bit stupid to do something with a NULL name */
  86     if( name )
  87     {
  88         /*
  89             if the user supplied a lastObject, then we shall use that
  90             to get the index of the starting object. Otherwise we shall
  91             extract the address of the first node in the NameSpace.
  92         */
  93         if(lastObject)
  94             StartObj = (GetIntNamedObject(lastObject))->no_Node.ln_Succ;
  95         else
  96             StartObj = (struct Node *)ns->ns_List.mlh_Head;
  97
  98         if((no = IntFindNamedObj(ns, StartObj, name, UtilityBase)))
  99         {
 100             no->no_UseCount++;
 101             foundObj = GetNamedObject(no);
 102         }
 103
 104     } /* if( name ) */
 105     else /* if(name == NULL) */
 106     {
 107         if(lastObject)
 108             foundObj = (struct NamedObject *)(
 109                 (GetIntNamedObject(lastObject))->no_Node.ln_Succ
 110             );
 111         else
 112             foundObj = (struct NamedObject *)ns->ns_List.mlh_Head;
 113     }
 114     ReleaseSemaphore( &ns->ns_Lock );
 115
 116     return foundObj;
 117
 118     AROS_LIBFUNC_EXIT
 119
 120 } /* FindNamedObject */