Simplified Sausalito Client API Specification
---------------------------------------------
$Id: Class.spec.txt,v 1.3 2000/05/03 20:42:44 jmayer Exp $
author: Jonathan "I can't believe I'm still writing specs" Mayer

OBSOLETE ------------------------------------------------ OBSOLETE

	This document is obsolete.  A formal document
	describing the C client API will replace it shortly.

OBSOLETE ------------------------------------------------ OBSOLETE


------------
1.0 Overview
------------

	The CCE Client Library is a library that facilitates communication
  betweens a client (ie. UI, remote admin, handler) and the sauced
  server.

  The client library defines a convenient way to perform the following
  operations:
    - modify and view the attributes of the system
    - create, modify, destroy, and view virtual sites
    - create, modify, destroy, and view users
    - modify and view service settings
    - create, modify, destroy, and view mailing lists

--------
2. Terms
--------

  Class: "System", "Site", "User", "MailList", etc.
  
  Object: An instance of a class.
  
  Attributes: key/value pairs that represent the properties of an object.
  
  Namespace: A means of subdividing the attribute names within an object,
  	so that each attribute within a namespace can have it's own name
    without worrying about whats going on in the other namespaces.

----------------------
3. Objects and Methods
----------------------

3.1.1 Summary
-------------

	The following objects are defined here:
  
    cce_handle_t - a handle for the connection to the back end.

    cce_oid_t  - a cce object id
    cce_oidlist_t - a list of cce object ids.
    cce_namelist_t - a list of cce namespace names.
    cce_error_t - an error code, key and message.
    cce_errors_t - a list of warnings and errors.
    cce_props_t - a handle to a CCE object.

3.1.2 Memory Management
-----------------------

	The objective is the minimize the amount of memory management the client
  application will have to perform using the CCE client library.  This is
  acheived in the following manner.
  
  The client need only worry about the construction and destruction of the
  "cce_handle_t" object (the connection handle).  The cce_handle_t object
  should then keep track of any additional dynamic memory that is allocated
  by any cce_[handle|\w+_cmnd] functions and free them upon it's own
  destruction.

3.2 cce_oid_t
-------------

  An object identifier.  Every object in the object database is identified
  by a unique object identifier.
  
    cce_oid_t is defined to be an unsigned long integer.
  
  The object identifier value zero ("0") does not identify any valid
  object, and is instead used to flag undefined or erroneous states.
  
    No explicit methods are defined for object id.
  
3.3 cce_oidlist_t
-----------------

  A list of object identifiers (cce_oidlist_t).
  
  cce_oidlist objects are never created or destroyed by the user, but
  are automatically created by the cce_handle object, and are automatically
  destroyed when the cce_handle object is destroyed.
  
  The following public methods are defined:
  
    int cce_oidlist_length(cce_oidlist_t *)
    
    	Returns: the number of objects in the list.
    
    cce_oid_t cce_oidlist_first(cce_oidlist_t *)
    
        Returns: the first OID in the list, or 0 if the list is empty.
      
      Additionally, the lists internal pointers are reset such that
      a subsequent call to cce_oidlist_next will give the second,
      then the third, etc., oids in the list.
    
    cce_oid_t cce_oidlist_next(cce_oidlist_t *);
    
        Returns the next OID in the list, or 0 if the list has been
      exhausted.
    
    cce_oid_t cce_oidlist_seek(cce_oidlist_t *, int n);
    
        Returns the "nth" object id in the oid list (when 0 represents
      the first object in the list).  Additional, the lists internal
      pointers are reset, so that cce_oidlist_next will return the
      element after the selected object.

	The following private methods are defined, but are not part of
  the public Client API:
  	cce_oidlist_t * cce_oidlist_new();
    void cce_oidlist_destroy();
    void cce_oidlist_append(cce_oidlist_t *, cce_oid_t oid);

3.4 cce_namelist_t
------------------

	A list of namespace names.
  
  cce_namelist objects are never created or destroyed by the user, but
  are automatically created by the cce_handle object, and are automatically
  destroyed when the cce_handle object is destroyed.
  
  The following public methods are defined:
  
    int cce_namelist_length(cce_namelist_t *)
    
    	Returns: the number of names in the list
    
    char * cce_namelist_first(cce_namelist_t *)
    
      Returns the first name in the list, or NULL if the list is empty.  
      Also, sets the list's internal pointer to the beginning of the list.

    char * cce_namelist_next(cce_namelist_t *);

      Returns the next name in the list, advancing the list's
      internal pointer by one.  If no more names are available,
      returns NULL instead.
	  
    char * cce_namelist_seek(cce_namelist_t *, int n);
    
      Sets the internal pointer to point to the nth element of the list,
      and returns that element.

	The following private methods are defined, but are not part of
    the public Client API:
 
    cce_namelist_t * cce_namelist_new();
    void cce_namelist_destroy();
    void cce_namelist_append(cce_namelist_t *, cce_oid_t oid);

3.5 cce_props_t
--------------

  This is a generic hash object, used to represent either the
  attributes of an object, or a list of attribute errors in the
  event of a failed CREATE or SET command.

    cce_props_t * cce_props_new();
    void cce_props_destroy(cce_props_t* props);
    
    int cce_props_set ( cce_props_t*, char *key, char *value);
    char * cce_props_get ( cce_props_t*, char *key );

    void cce_props_reinit ( cce_props_t* );

        Reinits the list of available keys. Shoudl always be called
		before iterating.

	int cce_props_next ( cce_props_t*, char **key, char **value);

	Notes:
  	cce_props_assign should always make copies of the key and value
    strings, as well as being careful to free any inserts over previous
	data.

3.6 cce_error_t
---------------

  cce_error_t is a transperant data structure that has no methods.

  It's attirbutes are

    code
	
	  The code of the error.

	key
	
	  The key the the error occured in.

	message

	  Text explainging the error if applicable.

	Different error codes use the attributes differently. An unknown key error
	will fill in the key attribute but leave message set to NULL.

	UNKNOWN_CLASS
	    Does not use key or message.
	UNKNOWN_NAMESPACE
	    Does not use key or message.
	BAD_KEY
	    key holds the name of the unknown attribute.
	BAD_DATA
	    key holds the bad key, message holds the reason it was bad.
	ERROR
	    Message holds an error message. This should not be used. If there is
	    an error that does not fit into the api, something is wrong.

3.7 cce_errors_t
--------------

    A structure that contains a list of messages returned by certain
  cce commands.  It is created and destroyed by the cce_handle object,
  and so should not be created or destroyed by the user.
  
  char * cce_resp_first ( cce_resp_t * );
  
  	Sets the cce_resp object's internal pointer to point to the first
    message, and returns that message (or NULL if the list is empty).
  
  char * cce_resp_next ( cce_resp_t * );
  
  	Advances the cce_resp object's internal pointer to the next message,
    and returns that message (or NULL if the list is empty).
  
  int cce_resp_length ( cce_resp_t * );
  
  	Returns the total number of messages in the cce_resp object.

  int cce_resp_warnings ( cce_resp_t * );
  
  	Returns the total number of warning messages in the cce_resp object.

  int cce_resp_errors ( cce_resp_t * );
  
  	Returns the total number of error messages in the cce_resp object.

3.8 cce_handle_t
----------------

	The following methods are assocaited with the cce_handle_t type:

	cce_handle_t * cce_handle_new ()
		Constructor: creates a new connection handle to the CCE server.
		Returns: a pointer to a newly constructed cce_handle object.

	void cce_handle_destroy (cce_handle_t *)
		Destructor: destroys a cce_handle object, and all of the dynamic
		            memory allocated by the cce_handle object.

  int cce_connect_cmnd(cce_handle_t *)
    Connects to the socket. There are good reason to do with internal
		implementation why this is nto part of the constructor.

	The following functions map directly onto CSCP commands.  See the CSCP
  documentation for details.
  
  int cce_auth_cmnd ( cce_handle_t *, char * username, char * password );
  
  int cce_create_cmnd ( cce_handle_t *, char *classname, 
  	cce_props_t *attr, g_hash_t *errors );
  
	int cce_destroy_cmnd ( cce_handle_t *, cce_oid_t oid );
	
  int cce_set_cmnd ( cce_handle_t *, cce_oid_t oid, 
  	g_hash_t *attr, g_hash_t *errors );

	int cce_get_cmnd ( cce_handle_t *, cce_oid_t oid, g_hash_t *attr );
  
  cce_errors_t* cce_commit_cmnd ( cce_handle_t * );
  
  cce_namelist_t* cce_names_class_cmnd ( cce_handle_t *, char *class );
  cce_namelist_t* cce_names_oid_cmnd ( cce_handle_t *, cscp_oid_t oid );
  
  cce_oidlist_t* cce_find_cmnd (cce_handle_t *, g_hash_t *criteria );
	  
	The following functions only make sense in the context of an event
  handler (as opposed to an ordinary, UI-style client):

  cce_hinfo_t *cce_

	int cce_bad_key_cmnd ( cce_handle_t *, cce_oid_t oid, 
  	char *namespace, char *key );
    
  int cce_bad_value_cmnd ( cce_handle_t *, cce_oid_t oid, 
  	char *namespace, char *key );
    
  int cce_bye_handle_cmnd(cce_handle_t *, cce_ret_t state);
		Where cce_ret_t is an enum of SUCCESS, DEFER, FAIL.

		Says goodbye with a reason for the handler.
 
----------------------------------
4.0 Class and Property Definitions
----------------------------------

This section defines and describes all the valid properties for every
predefined class in this sytem.

All objects share the following properties, which are visible from
every namespace:
	OID -- the oid of the object, represented as a string.
  CLASS -- the name of class the object is an instance of.
  NAMESPACE -- the namespace of this subset of the object's properties.

4.1 System object attributes
----------------------------

  In any given product, there will only be one system object.  It never
  needs to be created and it is never destroyed.  Attributes of the system
  object define global system-wide settings.

  Valid system properties are:

    hostname 
    domainname
    eth0_ipaddr
    eth0_netmask
    eth0_up
    eth1_ipaddr
    eth1_netmask
    eth1_up
    eth1_avail (Read only)
    gateway
    dns_primary
    dns_secondary
    notify_email

    time_region
    time_country
    time_zone

    sitedef_ipaddr
    sitedef_domainname
    sitedef_quota
    sitedef_maxusers

    reboot

4.2 Site object properties
--------------------------

  Site objects are dynamically created and destroyed.  Creating a site
  object is analagous to creating a new virtual site, and destroying it
  deletes the virtual site.  Site object properties are specific to a
  single virtual site.

  Valid site properties are:
    name
    hostname
    domainname
    maxusers
    quota
    ipaddr
    netmask
    enabled

4.3 Group object properties
---------------------------

  Valid group properties are:
    name
    quota
    members  (":" delimited, e.g. ":user1:user2:")
    enabled

4.4 User object properties
--------------------------

  User objects are dynamically created and destroyed.  Creating a user
  object is analagous to adding a user to the system.  Destroying a
  user object is analagous to removing a user from the system.  User
  object properties are specific to a single user within the system.

  Valid user properties are:
    name
    fullname
    sortname
    enabled
    uid 
    gid
    home
    shell
    password
    sysadmin (flag)
    siteadmin (flag)
    site (a single siteId)
    localePreference
    stylePreference

4.5 MailList object properties
------------------------------

  properties:
    name
    password
    allow_subscriptions
    allow_unsubbed_posting
    local_recipients
    remote_recipients
    site

4.6 Service properties
----------------------

  Each service configuration object can be thought of as a separate
  service-specific namespace for attributes attached to each class of
  object (System, Site, and User).

  There are five levels of service configuration properties, for convenience
  aliterated A through E.

	  Class   Specific To  SystemAdmin  SiteAdmin  User
	  -----   -----------  -----------  ---------  ----
	  A       Global       R/W          r/o        r/o
	  B       Site         R/W          r/o        r/o
	  C       Site         R/W          R/W        r/o
	  D       User         R/W          R/W        r/o
	  E       User         R/W          R/W        R/W

  Here the properties for each service are listed out by class.  Note that the
  "enabled" property in the A class is a distinct property from the "enabled"
  propert in the B class.  (Think of each class as having its own namespace).
  In this example, this allows a site admin to turn on and off the enabled
  property for her site, without impacting the preferred settings of her
  site's users.

  For every service name, the following tags are assumed to exist in
  the i18n database:
    (service)   - the internationalized name of the service
    (service)-help  - the internationalized help text of the service

  The specific properties associated with each service, for each class,
  are summarized below.  As new services are added to the system, this
  list will grow.

  BandwidthManagement
    A: enabled, limit, url
    B: (none)
    C: (none)
    D: (none)
    E: (none)

  ShellAccess
    A: enabled
    B: enabled
    C: enabled
    D: enabled
    E: enabled

  Email
    A: enabled
    B: enabled
    C: enabled
    D: enabled
    E: enabled, aliases, forward, vacation, url

  FTP
    A: enabled, maxusers, quota, url
    B: enabled
    C: enabled
    D: enabled
    E: enabled

  SSL
    A: enabled, certificate, url
    B: enabled
    C: enabled, certificate, url
    D: (none)
    E: (none)

  FPX
    A: enabled
    B: enabled
    C: enabled
    D: (none)
    E: (none)

  CGI
    A: enabled
    B: enabled
    C: enabled
    D: (none)
    E: (none)

  PHP3
    A: enabled
    B: enabled
    C: enabled
    D: (none)
    E: (none)

  SSI
    A: enabled
    B: enabled
    C: enabled
    D: (none)
    E: (none)

  Web
    A: enabled
    B: enabled
    C: enabled
    D: (none)
    E: (none)

  POP3
    A: enabled
    B: enabled
    C: enabled
    D: (none)
    E: (none)

  IMAP
    A: enabled
    B: enabled
    C: enabled
    D: (none)
    E: (none)

  NTP
    A: enabled, server, url
    B: (none)
    C: (none)
    D: (none)
    E: (none)


  MailList
    A: enabled
    B: enabled
    C: enabled
    D: (none)
    E: (none)

  DNS
    (Fixme)

  SNMP
    A: enabled, readonly, readwrite, url
    B: (none)
    C: (none)
    D: (none)
    E: (none)

  DHCP
    A: enabled
    B: enabled
    C: enabled
    D: (none)
    E: (none)

  Postgres
    A: enabled

  MySql
    A: enabled

  Interbase
    A: enabled

  PrintSpool
    A: enabled, device, printertype, url

  LDAP
    A: enabled
    B: enabled
    C: enabled

  Firewall
    FIXME

  Appleshare
    FIXME

  Samba
    FIXME

  NFS
    FIXME

  Backup
    A: enabled, ServerHostname, ServerIPAddr, url

  AutoUpdate
    A: enabled, server, url

4.7 DomainMap properties
------------------------

  The DomainMap hash table is used to "route" generic domain
  names (the keys of the hash) to unique siteIds (values).  This
  specifies the default site to use for operations that only
  specify a domain (ie. email delivery, web service, etc.).

  Unlike the other objects defined above, the domainmap object can does not
  have a specific list of properties -- it functions more as a general hash. 
  Each key in this hash indicates a domain name, while the value of each hash
  entry indicates which unique site to associate with that domain.
