CMS API convention and style notes
----------------------------------

Last updated: March 10, 1998
Cindy Grall

This note is meant to summarize the CMS API conventions used and
notes on coding style.  This is so that changes and additions to
the API will be consistent with the existing code.  None of these
items are "hard" or "fast" rules, exceptions currently exist and
if you need to do something different that's okay.  But, keep in
mind that a consistent API is easier to use, so when possible, try
to stick to these conventions.

These are in no special order:


* Naming conventions

API calls start with "tc_".  Internal calls/utilities that a user would
never use do not need to follow this convention.

Defines and other constants start with "TC_".

Use underlines between words in a name.

(note, "tc" stands for TIS/CMS)


* Routine Parameters

Output and input/output parameters are first.

Input parameters are next.

If the context is used, it will be last.


* Error handling

Most API interfaces are functions that return an integer status
code.  Zero (0) is returned for success, negative numbers otherwise.
All other output values for the function are reference parameters
in the function call.

tc.h contains the current list of defined error codes. New ones can
be added, just be sure to add appropriate entries to TC_errlist[]
in error.c.

An exception to this exists for "math-like" functions (eg., 
tc_compare_serial or tc_get_choiceoftime).  In these cases the
return is usually the "math" value.

Always check user provided parameters.


* Memory handling

When possible, an API routine allocates any needed memory.  The
caller provides an address pointer for the routine to return the 
pointer of the allocated space.

The user is responsible for free'ing memory when no longer needed.  If
the data in question is a complicated structure then an API routine
should be provided to free the space (eg., tc_free_cert).

When feasible, copy all provided data into locally allocated space.
Currently some calls do not do this (eg., tc_add_cert only uses the
pointer, it does not create a local copy of the CERT).

When feasible, always return a copy of any requested data. A few 
exceptions currently exist in the API (eg., tc_find_cert).