Simplified Sausalito Client API Specification --------------------------------------------- $Id: Class.spec.txt,v 1.1.1.1 2005/08/12 16:41:16 dodell 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 gmake 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 gmake 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.