pbms_add_metadata
Description
pbms_bool pbms_add_metadata ( PBMS pbms, const char * name, const char * value )
Adds metadata to be associated with the next BLOB uploaded to the PBMS BLOB streaming server.

The metadata remains associated with the connection until it is cleared by calling pbms_clear_metadata().

If pbms_add_metadata() is called multiple times with the same name and pbms_clear_metadata() is not called then multiple instances of the metadata will be added.

The metadata name must exist in the PBMS system table 'pbms_metadata_header' before the PBMS BLOB streaming server will store it with the BLOB data. Each database has it's own 'pbms_metadata_header' table which is created automatically the first time it is referenced.

Parameters
pbms
A valid PBMS connection handle.
name
The name of the metadata field.
value
The value to be associated with the name.
Return Values

Returns TRUE on success.

Returns FALSE on failure. Use pbms_errno() and pbms_error() to retrieve error details.

Example
		
char buffer[80], *theBLOB;
char name[PBMS_META_NAME_SIZE];
size_t size;
unsigned int cnt;

pbms = pbms_connect("localhost", 8080, "aDatabase");

// Let PBMS know about our custom headers we want to store with the BLOB
// assuming the names are not already in the pbms_metadata_header table.
mysql_query("insert into pbms_metadata_header(name) Values('Header1')");	
mysql_query("insert into pbms_metadata_header(name) Values('Blob Name')");	
mysql_query("insert into pbms_metadata_header(name) Values('Blob Info')");	

pbms_add_metadata(pbms, "Header1", "PHPTest");
pbms_add_metadata(pbms, "Blob Name", "Little BLOB");

// Add 2 metadata name value pairs with the same name.
pbms_add_metadata(pbms, "Blob Info", "Some info");
pbms_add_metadata(pbms, "Blob Info", "Some more info");

theBLOB = "A tiny BLOB";
pbms_put_data(pbms, NULL, blob_ref, strlen(theBLOB), theBLOB);

//-----------
pbms_get_info(pbms, blob_ref); // Get the BLOB info.

size = 80;
pbms_get_metadata_value(pbms, "Header1", buffer, &size);
printf("Header1: %s\n", buffer);

size = 80;
pbms_get_metadata_value(pbms, "PHPTest", buffer, &size);
printf("PHPTest: %s\n", buffer);

size = 80;
pbms_get_metadata_value(pbms, "Blob Info", buffer, &size);
printf("One of the Blob Info headers: %s\n", buffer);

// To get both "Blob Info" headers you need to scan all the headers:
cnt = pbms_reset_metadata(pbms); 
while (cnt) {
	size = 80;
	pbms_next_metadata(pbms, name, buffer, &size);
	if (strcmp(name, "Blob Info") == 0)
		printf("Blob Info: %s\n", buffer);
	cnt--;
}



pbms_close(pbms);
		
Related functions
pbms_clear_metadata()