Finding Advertisables

A common use case for the GATAdvertService is one in which an application searches in a GATAdvertService for an advertisable which fits a certain description. For example, one may try and search for all descriptions containing the key/value pair ``owner/Leonardo''. A search of this type is accomplished through us of the following function

GATResult GATAdvertService_Find(GATAdvertService_const object, 
                                GATTable_const metadata, 
                                GATList_String *paths)

The first argument to this function is the GATAdvertService whose contents are to searched. The second argument to this function is a GATTable the description of the advertisable the search will find. As one will recall, this is a set of key/value pairs in which the key is a standard C string not beginning with GAT_ and the value is also a POSIX regular expression expressed as a standard C string. The final argument to this function is a pointer to a GATList_String. It is through this pointer that the search's results are returned to the caller. The results are presented as a list of standard C strings in which each string contains a POSIX path to an advertisable matching the passed description. Finally this function returns a GATResult, covered in Appendix , which indicates the completion status of this function.

As an example of this function in action, consider creating a command line tool which, given a description in the form of a set of key/value pairs, prints out a list of POSIX paths of the various advertisables which fit the passed description. Such a command line to might have within its code a function which, when passed a GATTable describing the desired advertisables, passes back a list of standrd C strings each containing the POSIX path of an advertisable which fits the passed description. Such a function might look like this

GATResult GetPaths( GATTable_const description, GATList_String *paths )
{
  GATResult result;
  GATContext context;
  GATAdvertService advertService;
  
  result = GAT_MEMORYFAILURE;
  
  context = GATContext_Create();
  if( NULL != context )
  {
    advertService = GATAdvertService_Create( context, NULL );
    if( NULL != advertService )
    {
      result = GATAdvertService_Find( advertService, description, paths );
      
      GATAdvertService_Destroy( &advertService );
    }
    GATContext_Destroy( &context );
  }
  
  return result;
}