Getting or Deleting an Advertisable

After obtaining the POSIX path of an advertisable in an GATAdvertService usually one would like to get the actual advertisable instance located at this POSIX path. This is done through the following function

GATResult GATAdvertService_GetAdvertisable( GATAdvertService_const object,  
                                            GATString_const path, 
                                            GATObject *advertisable)

The first argument to this function is the GATAdvertService from which the advertisable is to be gotten. The second argument to this function is a GATString instance containing the POSIX path of the advertisable to extract. The final argument is a pointer to a GATObject. It is through this pointer that the GATAdvertService returns to the caller the advertisable located at the passed POSIX path. One should note that this call does not delete the advertiable from the GATAdvertService. It simply hands the caller a ``clone'' of the advertiable placed in the GATAdvertService. Finally, this function returns a GATResult, covered in Appendix , which indicates the completion status of this function.

To take this function out for a test drive consider the case in which code on machine A has placed a GATFile into the GATAdvertService under some fixed POSIX path then through some means transfers this POSIX path to machine B which is supposed to get this advertiable from the GATAdvertService. Such an application on machine B would likely have a function of the following form

GATResult GetAdvertisable( GATString_const path, GATObject *advertisable )
{
  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_GetAdvertisable( advertService, path, advertisable );
      
      GATAdvertService_Destroy( &advertService );
    }
    GATContext_Destroy( &context );
  }
  
  return result;
}

After getting an advertisable at a given path from the GATAdvertService it is often the case that one wishes to actually delete the corresponding advertisable from the GATAdvertService. As mentioned above, the act of getting the advertisable simply gives the caller a ``clone'' of the advertisable placed in the GATAdvertService. The actual advertisable, after such a ``Get,'' still resides in the GATAdvertService. To delete such an advertisble from the GATAdvertService one uses the function

GATResult GATAdvertService_Delete(GATAdvertService as, GATString_const path)

The first argument to this function is the GATAdvertService from which the advertisable is to be removed. The second argument is a GATString which contains the POSIX path of the advertisable to be removed from the passed GATAdvertService. This function also returns a GATResult, covered in Appendix , which indicates the completion status of this function. Upon successful completion of this function the advertisable associated with the specified POSIX path will be removed from the GATAdvertService.

If we continue in the same vein as the previous example, we may, after getting the advertisable form the GATAdvertService, wish to delete the advertisable from the same GATAdvertService as no other processes will have need for such an advertisable. If the application on machine B were indeed to do so, then it might have a function of the following form to accomplish this goal

GATResult DeleteAdvertisable( GATString_const path )
{
  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_Delete( advertService, path );
      
      GATAdvertService_Destroy( &advertService );
    }
    GATContext_Destroy( &context );
  }
  
  return result;
}