Obtaining the Description of an Advertisable

After placing an advertisable in a GATAdvertService or having someone else place an advertisable in a GATAdvertService that you wish to examine, it's often the case that one needs to obtain a description of the advertiable at a givan POSIX path. This is accomplished through the function

GATResult GATAdvertService_GetMetaData( GATAdvertService_const object, 
                                        GATString_const path, 
                                        GATTable *metadata)

The first argument to this function is the GATAdvertService to be probed for information. The second argument is a GATString containing a POSIX path. This is the path of the advertisable we wish to obtain the description of. the final argument to this function is a pointer to a GATTable. Through this pointer the caller is returned the description, a GATTable instance, associated with the advertisable when it was placed in the GATAdvertService. This function returns a GATResult, a type covered in Appendix , which indicates this function's completion status.

As an example consider the case in which on machine A some code has placed many advertisables into a GATAdvertService then given you, on machine B, the list of the POSIX paths of all these advertisables. You want to use some, but not all, of these various advertiables, but only one which have a description that jibes with you goals. So, to examine the description of these various advertiables you would need to write a function which, given a POSIX path, returns a description of the corresponding advertisable. The function might look a bit like the following

GATResult GetDescription( GATString_const path, GATTable *description )
{
  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_GetMetaData( advertService, path, description );
      
      GATAdvertService_Destroy( &advertService );
    }
    GATContext_Destroy( &context );
  }
  
  return result;
}