Adding Advertisables to an AdvertService

Now as we have mastered the art of creating and destroying GATAdvertService instances let us next move on to the task of adding advertisables to an GATAdvertService instance. This is done through a call to the following cunningly named function

GATResult 
  GATAdvertService_Add( GATAdvertService object, 
                        GATObject_const advertisable,
                        GATTable metadata, 
                        GATString_const path)

The first argument to this function is a GATAdvertService instance. This is the instance to be modified. The next argument is a GATObject instance. This is the advertisable which is to added to the GATAdvertService and hence must be an instance of a class which implements the interface GATInterface_IAdvertisable. The next argument is a GATTable, a class covered in Appendix . This GATTable instance contains the description of which we spoke earlier. This description takes the form of a set of name/value pairs in which the value is always a standard C string. For example, I might place an advertisable in a GATAdvertService instance with the name/value pair ``owner/Leonardo'' if I wanted to indicate that the particular instance I was placing was owned by Leonardo. Generically, one can use any C string for a key and any C string for a value. However, the keys beginning with GAT_ are reserved for internal use by the GAT engine and the values may be what are called a ``regular expressions.'' The reader not familiar with regular expressions should refer to Appendix . The final argument to this function is a GATString, a class covered in Appendix . Each entry in a GATAdvertService has associated with it a POSIX path, for those readers unfamiliar with the details of POSIX paths refer to Appendix . This GATString instance contains a string representing the POSIX path which is to be associated with the advertisable passed as this function's second argument. Finally this function returns a GATResult, the details of which are covered in Appendix , indicating its completion status.

As an example of this engine in action let us consider placing the a GATFile instnace in a GATAdvertService. This would look as follows

GATFile file;
GATResult result;
GATTable table;
GATString string;
GATObject object;
GATAdvertService advertService;

file = ...
table = ...
advertService = ...
string = GATString_Create( "/tmp/trash", 11, "ASCII" );

object = GATFile_ToGATObject( file );

result = GATAdvertService_Add( advertService, object, table, string );

if( GAT_SUCCEEDED( result ) )
{
  /* The file has been added to advertService with path string and meta-data table */
}