Subject: Attribute API

From: Evan Hughes <[email-masked]>
Date: Tue, 27 Jun 2000 18:01:52 -0400 (EDT)

Here's a first try at the attribute API. This suggestion includes as much
reasonable/useful functionality as I could think of, and may require some
reduction. 

Some possible reductions:
 Reducing SLPAttrGet_*() to SLPAttrGet(), and losing all template-based
type checking. 
 Ditto for SLPAttrSet().
 Dropping the "lazy" parameter to SLPAttrSet*() and forcing all copies to
be made on the function call. 

Here it is (Note, this does not include iterators). 

---CUT HERE---

Proposed SLP Attribute API

Data Structures:

The Attribute API requires three data-structures: a container to hold the 
attributes, an iterator to loop over the attributes, and a type enumberation. 
The container is:

typedef void *SLPAttributes;

The SLPAttributes type is either returned (as the result of an attributes 
request), or explicitly allocated (during attribute registration). It serves
as a handle to an arbitrary number of attributes, which can be added to,
iterated over, or submitteed to the SA/DA. Even though it is possible to
associate an instance of SLPAttributes with a template, only the values that
are explicitly set by the application will be sent to the SA/DA on update. 
The type is opaque.

The iterator is:

typedef void *SLPAttrIterator;

The SLPAttrIterator is explicitly allocated to iterate over an instance of the
SLPAttributes type. It is an opaque type.

The type enumeration is:

typedef enum {
	SLP_BOOLEAN = 1,
	SLP_INTEGER = 2,
	SLP_KEYWORD = 3, 
	SLP_STRING = 4,
	SLP_OPAQUE = 5
} SLPType;

Each value corresponds to a type specified in RFC 2609.

Creation/Destruction:

#include <slp.h>
#include <stdio.h>

SLPError SLPAttrAlloc(
		const char *lang, 
		const FILE *template_h,
		const SLPBoolean strict, 
		SLPAttributes *slp_attr
)

 Description:

 SLPAttrAlloc() creates and initializes a new instance of SLPAttributes. 

 Parameters:

  lang

  A pointer to a NULL terminated array of characters containing the RFC 1766
  Language Tag for the natural language locale of requests and registrations
  issued on the handle.  Pass in NULL or the empty string, "" to use the local
  the machine is configured to use.  

  template_h

  An open filehandle to the template that these attributes are to conform to. 
  May be NULL if type checking is not desired. The API will leave the file
  handle open, but pointing to the eof.

  strict

  A boolean flag specifying how strict the API should be when verifying tag
  names against the template specified by template_h. If this field is SLP_TRUE,
  then any attempt to register an invalid tag name/type will fail, and
  SLP_TYPE_ERROR will be returned. If this field is SLP_FALSE, the registration
  of invalid tag names will succeed, but a SLP_TAG_WARNING message will be 
  returned. 

  If template_h is NULL, the value of strict must be ignored.

  slp_attr

  A pointer to an SLPAttributes handle, through which the instance is
  returned. 

 Returns:

  SLP_OK
   If the SLPAttributes were instantiated properly. 
  SLP_LANGUAGE_NOT_SUPPORTED
   If the lang specified is not supported. This will occur if the template
   specified in the template_h is not of the requested language. Note:
   Allocation and initialization must not occur. The application may request
   again with the template_h field set to NULL.  
  SLP_PARSE_ERROR
   If the template is not of the required format. As with
   SLP_LANGUAGE_NOT_SUPPORTED, allocation does not occur. 
  SLP_MEMORY_ALLOC_FAILED
   If the API ran out of memory.
  SLP_INTERNAL_SYSTEM_ERROR
   An unspecified error occured.
  SLP_NOT_IMPLEMENTED
   If the function is not implemented.

SLPError SLPAttrFree(
		SLPAttributes attr_h
)

 Description:

 Deallocates all resources held by the specified instance of SLPAttributes. 

 Parameters:
  attr_h

  The attribute handle specifying the attributes to be deallocated. 

 Returns:
  SLP_OK
   If the SLPAttributes were deallocated properly.
  SLP_INTERNAL_SYSTEM_ERROR
   An unspecified error occured.

#include <slp.h>

SLPError SLPAttrIteratorAlloc(
		SLPAttributes attr_h,
		SLPAttrIterator *iterator,
)

 Description:

  Creates and initializes an iterator for use with a set of attributes. 

 Parameters:

  attr_h

  Handle to the attributes to iterate over. 

  iterator

  The new iterator is allocated and returned through this field. 

 Returns:

  SLP_OK
   If instantiation occured properly.
  SLP_MEMORY_ALLOC_FAILED
   If the API ran out of memory. 
  SLP_PARAMETER_BAD
   If the value of attr_h is NULL.
  SLP_NOT_IMPLEMENTED
   If the function is not implemented.

Attribute Manipulation:

The attribute manipulation functions are made available by type. There are
five "sets", and five "gets", each corresponding to one of the five types SLP
is aware of. Each takes a value from the application and performs all
necessary operations to allow the SLPReg() function to send it across the
network. 

The only 

#include <slp.h>

SLPError SLPAttrSet_bool(
		SLPAttributes attr_h,
		const char *attribute_tag,
		SLPBoolean val
)

 Description:

  Sets the value of the named boolean attribute to that of the passed value. 
  If the value of the named attribute has already been set, it is reset. 

 Parameters:

  attr_h

  Attribute handle to set in.

  attribute_tag

  The name of the attribute to set. Must be a NULL terminated string.

  val

  The value to set the variable to. 

 Returns:

  SLP_OK
   If the value of attribute_tag is valid (according to the template), and
   value of attr_h is not NULL.
  SLP_TAG_WARNING
   If the attribute_tag is not in the template the attr_h was initialized
   with, and the strict flag is clear (SLP_FALSE), this warning will be 
   returned. 
   Note: the value IS set. 
  SLP_TAG_ERROR
   If the attribute_tag is not in the template attr_h was initialized with,
   and the strict flag is set (SLP_TRUE), this error is returned. 
   Note: the value is NOT set. 
  SLP_TYPE_ERROR
   Returned if a variable with the attribute_tag exists in the template, but 
   has a different type. The strict value has no effect on this return value. 
   Note: The value is NOT set. 
  SLP_MEMORY_ALLOC_FAILED
   If an internal allocation failed. 
  SLP_PARAMETER_BAD
   If the passed value is neither SLP_TRUE nor SLP_FALSE.
  SLP_INTERNAL_SYSTEM_ERROR
   Some misc. error. 
  SLP_NOT_IMPLEMENTED
   If the function is not implemented.

#include <slp.h>

SLPError SLPAttrSet_int(
		SLPAttributes attr_h,
		const char *attribute_tag,
		const int val
)

 Description:

  Sets the value of an integer variable. 

 Parameters:
  See SLPAttrSet_bool(). 

 Returns:
  See SLPAttrSet_bool(). 

#include <slp.h>

SLPError SLPAttrSet_str(
		SLPAttributes attr_h,
		const char *attribute_tag,
		const char *val
)

 Description:

  Sets the value of a string variable. Note that the passed string is copied
  by the API.

 Parameters:
  See SLPAttrSet_bool(). 

  val

  val must be NULL terminated. It does not need to be explicitly escaped. 

 Returns:
  See SLPAttrSet_bool(). 

#include <slp.h>

SLPError SLPAttrSet_keyw(
		SLPAttributes attr_h,
		const char *attribute_tag,
		const char *val,
		const SLPBoolean lazy
)

 Description:

  Sets the value of a keyword variable.  

 Parameters:
  See SLPAttrSet_bool(). 

  lazy

  If the lazy variable is set (SLP_TRUE), the API will not copy the string
  contents until the SLPRegAttr() function is called. This saves unnecessary
  copies, but it does oblidge the application to keep the passed string
  available until SLPRegAttr() is called. 
  
  If the lazy variable is clear (SLP_FALSE), the API immediately copies the
  string; allowing the application to immediately dispose of the passed value.  

 Returns:
  See SLPAttrSet_bool(). 
  SLP_TYPE_ERROR
   If the value passed contains characters outside the range of *** to ***.

#include <slp.h>

SLPError SLPAttrSet_str(
		SLPAttributes attr_h,
		const char *attribute_tag,
		const char *val,
		const SLPBoolean lazy
)

 See SLPAttrSet_keyw(). 

#include <slp.h>

SLPError SLPAttrSet_opaque(
		SLPAttributes attr_h,
		const char *attribute_tag,
		const char *val,
		const unsigned int len,
		const SLPBoolean lazy
)

 Description:

  Sets the value of an opaque attribute.  

 Parameters:
  See SLPAttrSet_keyw().

  len

  The length of the opaque data field, in bytes. This allows NULL characters
  to be embedded in the string. 

  lazy

  See SLPAttrSet_keyw().

 Returns:
  See SLPAttrSet_bool(). 

#include <slp.h>

SLPError SLPAttrGet_bool(
		SLPAttributes attr_h,
		const char *attribute_tag,
		SLPBoolean *val
)

SLPError SLPAttrGet_int(
		SLPAttributes attr_h,
		const char *attribute_tag,
		int *val
)

 Description:

  Gets the value of an attribute. 

 Parameters:
  attr_h

  Attribute handle to get from. 

  attribute_tag

  The name of the attribute as a NULL terminated string. 

  val

  A pointer through which the attribute value can be returned.

 Returns:
  SLP_OK
   If the value is set properly. 
  SLP_TAG_ERROR
   If the attribute_tag is unknown. 
  SLP_TYPE_ERROR
   If the attribute could not be converted into the requested type. See the
   end of this section for a description of when this occurs.     
  SLP_MEMORY_ALLOC_FAILED
   If an internal allocation failed. 
  SLP_INTERNAL_SYSTEM_ERROR
   Some misc. error. 
  SLP_NOT_IMPLEMENTED
   If the function is not implemented.

#include <slp.h>

SLPError SLPAttrGet_str(
		SLPAttributes attr_h,
		const char *attribute_tag,
		char **val
		int *len
)

SLPError SLPAttrGet_keyw(
		SLPAttributes attr_h,
		const char *attribute_tag,
		char **val
		int *len
)

SLPError SLPAttrGet_opaque(
		SLPAttributes attr_h,
		const char *attribute_tag,
		const char **val,
		unsigned int *len
)

 Description:

  Gets the value of an attribute. 

 Parameters:
  attr_h

  Attribute handle to get from. 

  attribute_tag

  The name of the attribute as a NULL terminated string. 

  val

  A pointer through which the attribute value can be returned. The returned
  value must be collected with SLPFree(). 

  len

  A pointer through which the length of val can be returned. For 
  SLPAttrGet_keyw() and SLPAttrGet_str() the returned value MAY be -1, which
  indicates that the length of the string must be determined by the
  application. For SLPAttrGet_opaque() this value MUST be set by the API.

 Returns:
  SLP_OK
   If the value is set properly. 
  SLP_TAG_ERROR
   If the attribute_tag is unknown. 
  SLP_TYPE_ERROR
   If the attribute could not be converted into the requested type. See the
   end of this section for a description of when this occurs.     
  SLP_MEMORY_ALLOC_FAILED
   If an internal allocation failed. 
  SLP_INTERNAL_SYSTEM_ERROR
   Some misc. error. 
  SLP_NOT_IMPLEMENTED
   If the function is not implemented.

Note that an SLP_TYPE_ERROR will occur during a "get" when:
 SLPAttrGet_bool() is used to get an attribute whose value is anything other
    than a boolean.
 SLPAttrGet_int() is used to get an attribute whose value is neither an
    integer nor a boolean.
 SLPAttrGet_keyw() or SLPAttrGet_str() is used to get an opaque value (one
	that contains an unescaped character outside of the range *** to ***). 

Note that SLPAttrGet_opaque() can be used to get any value. 

Submitting to DA/SA:

#include <slp.h> 

SLPError SLPRegAttr( 
	SLPHandle slp_h, 
	const char* srvurl, 
	unsigned short lifetime, 
	const char* srvtype, 
	const SLPAttributes *attr_h, 
	SLPBoolean fresh, 
	SLPRegReport callback, 
	void* cookie 
) 

Same as the old version. Note that the old version (with explicit control over
the setting of the attribute string) should still exist. 

Finding the Type of an Attribute:

#include <slp.h>

SLPError SLPAttrType(
    SLPAttributes attr_h,
	const char *attribute_tag,
	SLPType *slp_type
)

 Description:

  Queries the type of the requested attribute. 

 Parameters:

  attr_h

  A handle to the attribute structue to query.

  attribute_tag

  The name of the attribute to query.

  slp_type

  A pointer to the type field to set. 

 Returns:
  SLP_OK
   If the attribute was queried and set. 
  SLP_TAG_ERROR
   The specified tag does not exist in attr_h.
  SLP_INTERNAL_SYSTEM_ERROR
   Any misc. error. 
  SLP_MEMORY_ALLOC_FAILED
   If a malloc failed. If this value is returned, the request failed. 
  SLP_NOT_IMPLEMENTED
   If the function is not implemented.