Developer reference manual

• Connection with repository management systems
  • Content management
  • File management
• Basic application programming interface
  • Repository management
  • Enquirers
  • Message management
  • Orders
  • Debugging and options
• Building an HTTP server
• Examples
  • Basic example
  • Server

This section concerns the integration of the CO₄ protocol, as a library, in a new application. It is a C developer manual. You must keep in mind that because of the use of KAPI, a KAPI error can occur. They are not listed below, and you must refer to the documentation available in the KAPI directory.

Connection with repository management systems

In order to build an application using CO₄, the developer must provide some functions defined as extern in libCo4. These functions deal with content management, while CO₄ only deals with transport. This covers initialisation, loading, saving, addition of content. To help writing these functions, CO₄ provides utilities functions to manage repository files located in the ANS.

Content management

extern int InitKnowledge()

called by Co4CreateRepository and Co4WakeUpRepository.
Initialises the content of the repository. Returns CO4_OK if successful.

extern int LoadKnowledge()

called by Co4WakeUpRepository.
Recovers the content of the repository from the ANS. Returns CO4_OK if successful.

extern int SaveKnowledge()

called by Co4ShutDown.
Saves the content of the repository on the ANS. Returns CO4_OK if successful.

extern char* DumpKnowledge()
Returns a string representing the complete content of the repository. This string will be sent by CO₄, then freed, so it must have been allocated.

extern int AddKnowledge(char*contentString)
Extracts the content from its string representation contentString and adds it to the current repository. By extension, must be able to treat the string returned by DumpKnowledge. Returns CO4_OK if successful.

extern int ConfrontKnowledge(char*contentString)
Extracts the content from its string representation contentString and confronts it with that of the current repository. Returns as Co4Test:
CO4_STATUS_ADMISSIBLE,
CO4_STATUS_CONTAINED,
CO4_STATUS_CONTRADICTORY.

extern char* IntersectKnowledge(char* k1, char* k2)
Returns an allocated string denoting the intersection of two pieces of knowledge, contained in two strings k1 and k2. This string will be freed by CO₄.

extern char* MergeKnowledge(char* k1, char* k2)
Returns an allocated string denoting the merge of two pieces of knowledge, contained in two strings k1 and k2. This string will be freed by CO₄.

File management

Some more functions might be necessary in order to deal with files stored in the ANS server and to retrieve and store them. They are provided here.

int Co4GetFile(char* ANSfilename, char* localFilename)
Copies the file ANSfilename located in the directory of the current repository by the ANS, to localFilename. Returns
CO4_OK: the file ANSfilename has been successfully transferred.
CO4_NO_FILE: the file ANSfilename cannot be accessed by the ANS.
CO4_ERROR: an error occurred.

int Co4SendFile(char* localFilename, char* ANSfilename)
Copies the local file localFilename to the file ANS filename located in the directory of the current repository by the ANS. Returns
CO4_OK: the file localFilename has been successfully transferred.
CO4_NO_FILE: the file localFilename cannot be accessed.
CO4_ERROR: an error occurred.

int Co4DeleteFile(char* ANSfilename)
Deletes the file ANS filename located in the directory of the current repository by the ANS. Returns:
CO4_OK: the file ANSfilename has been successfully deleted.
CO4_NO_FILE: the file ANSfilename does not exist by the ANS.
CO4_ERROR: an error occurred.

int Co4DeleteAllFiles()
Deletes the whole directory of the current repository by the ANS. Returns:
CO4_OK: the directory has been successfully deleted.
CO4_ERROR: an error occurred.

Basic application programming interface

The main header file co4.h defines the CO₄ protocol application programming interface (API):

Repository management

int Co4CreateRepository(char* ANSurl, char* name, char* KqmlUrl, int erase)
Tries to create the repository, via the given ANS. If it already exists (same ANS and same name), its behaviour depends on erase : if it is false, an error is returned. If it is true, all data are erased, and the repository created again. The ANS will communicate with the repository trough the URL given by KqmlUrl.
Returns CO4_OK if successful, otherwise one of the following error codes is returned:
CO4_NO_ANS_RESPONSE: the ANS does not respond.
CO4_NO_CONNECTION: KqmlUrl does not respond
CO4_IS_ACTIVE: the repository is still active.
CO4_ALREADY_EXISTS: erase is 0, and the repository already exists.
CO4_ERROR another error occurred.

int Co4WakeUpRepository(char* ANSurl, char* name, char* KqmlUrl)
Wakes up an existing repository, i.e. fetches repository content, info and processes pending messages. If KqmlUrl is NULL, uses the previous existing URL.
Returns CO4_OK if successful, otherwise one of the following error codes is returned:
CO4_NO_ANS_RESPONSE: the ANS does not respond.
CO4_NO_CONNECTION: KqmlUrl does not respond
CO4_IS_ACTIVE: the repository is still active.
CO4_DOESNT_EXIST: the repository does not exist.
CO4_ERROR: another error occurred.

int Co4SaveRepository()
Saves the repository.
Returns CO4_OK if successful, CO4_ERROR otherwise.

int Co4ShutDownRepository()
Calls Co4SaveRepository and shuts the repository down.
Returns CO4_OK if successful, CO4_ERROR otherwise.

int Co4DeleteRepository()
Discards the repository.
Returns CO4_OK if successful, CO4_ERROR otherwise.

void Co4TurnIntoGroup()
Turns the current repository into a group repository.

Enquirers

char* Co4GetGroupName()
Returns the name of the group repository of the current repository (default NULL).

int Co4IsGroupRepository()
Returns 1 if the current repository is a group one, 0 otherwise.

Message management

int Co4GetMessage(char *msg)
Tries to read a waiting message. If any, it is copied in msg, and the function returns CO4_OK, CO4_ERROR otherwise.

void Co4ProcessMessage(char* msg)
Processes a message.

Orders

Here are the functions for performing CO₄ orders like "register", "evaluate", "accept", etc. All functions can return CO4_UNKNOWN_RECEIVER if the receiver is not known by the ANS, CO4_UNREGISTRED if the current repository has not registered yet (all but Co4Register) and CO4_ERROR, denoting an internal error. Others errors are listed below.

Beware of the fact that return status only concerns the request emission and not the result of the request.

int Co4Register(char* grpname)
The current repository wants to register to grpname. Returns CO4_OK if the demand is successful, or an error code:
CO4_ALREADY_REGISTERED: already has a group repository.
CO4_BEING_REGISTERED: no answer yet
CO4_SELF_REGISTERED: a repository cannot register to itself.

int Co4Achieve(char* proposal)
Submits a new piece of knowledge to the group repository.
Returns CO4_OK, or one of the common errors.

int Co4Evaluate(char* proposal)
Makes the group repository evaluate a piece of knowledge.
Returns CO4_OK, or one of the common errors.

int Co4Forward(char* order, int depth)
Forwards a KQML order to depth levels forward, a depth of 0 meaning to the group repository, a depth of 1 meaning to the group repository of the group repository, and so on. Returns CO4_OK, or one of the common errors.

int Co4Deny(Co4Surrogate n)
Denies a previous ACHIEVE initiative or REGISTER, and so makes the group repository cancel its CFC. Returns CO4_OK, or an error code:
CO4_NO_SUCH_INITIATIVE: there is no initiative corresponding to the surrogate n,
CO4_CANT_DENY: the initiative does not correspond to an ACHIEVE or a REGISTER,
CO4_ALREADY_ANSWERED: the initiative is no more in a waiting state.

int Co4Accept(Co4Surrogate n)
Accepts a proposal. Returns CO4_OK, or an error code:
CO4_NO_SUCH_PROPOSAL: there is no proposal corresponding to the surrogate n,
CO4_ALREADY_ANSWERED: the initiative is no more in a waiting state.

int Co4Reject(Co4Surrogate n, char* comment)
Rejects a proposal with an explaining comment. Returns CO4_OK, or an error code:
CO4_NO_SUCH_PROPOSAL: there is no proposal corresponding to the surrogate n,
CO4_ALREADY_ANSWERED: the initiative is no more in a waiting state.

int Co4Challenge(Co4Surrogate n, char* new_proposal)
Challenges a proposal with an other KQML one. Returns CO4_OK, or an error code:
CO4_NO_SUCH_PROPOSAL: there is no proposal corresponding to the surrogate n,
CO4_ALREADY_ANSWERED: the initiative is no more in a waiting state.

int Co4Apply(Co4surrogate n)
Applies a new piece of knowledge sent by the group. Returns CO4_OK, or an error code:
CO4_NO_SUCH_TELL: there is no tell corresponding to the surrogate n,
CO4_CONTAINED if the knowledge is already present, or
CO4_CONTRADICTORY if it contradicts the repository.

int Co4Log(Co4surrogate n)
Logs a new piece of knowledge sent by the group. Returns CO4_OK, or an error code:
CO4_NO_SUCH_TELL: there is no tell corresponding to the surrogate n.

int Co4Test(Co4surrogate n)
Tests a new piece of knowledge sent by the group. Returns CO4_NO_SUCH_TELL, or one of the following
CO4_CONTAINED: the knowledge is already present,
CO4_CONTRADICTORY: the knowledge contradicts the repository,
CO4_ADMISSIBLE: the knowledge is admissible.

Debugging and options

extern int Debug
Forces KAPI to display low level information concerning TCP or HTTP communication (KAPI variable). Setting it to NoDebug (default) will hide these information. (see kapi.h for its possible values)

int oTrace

int oKeepAll

int oAnonymous

int oAcceptAll

int oAcceptMine
These variables are related to the CO4_* environment variables (see Customising in the User reference manual). If the repository is waken up, the values of these variables are restored. If it is created, they are all set to 0 (false). Then they are re-computed from their related environment variables, if present.

int oTellKnowledge
In some cases, depending on knowledge, only already existent knowledge can be submitted. So, when the knowledge has been accepted by all, it is normally told to each subscriber, but here not to the initial repository, because it already exists. To tell CO₄ whether it must tell or not the knowledge, set oTellKnowledge to 1 or 0.
The default behaviour is to tell knowledge. This variable is also saved and restored.

Building an HTTP server

CO₄ provide a HTML interface to be used by a browser via the Web. To do so, a CO₄ server must be created to communicate with the browser via a routing cgi-script. The file server.h contains the necessary functions.

void Co4ServerInit(char* routingScriptUrl, int port, int (*hook)(char*), char* knowledgeHome)
Initialises the server with the following parameters:

• routingScriptUrl: the URL of the routing script called by the browser (see ). For instance, "http://lotse.inrialpes.fr:1080/cgi-bin/co4exemple_server";
• port: the TCP port used by the server to communicate with the routing script, e.g. 6666;
• hook: the name of the function that will handle the queries to the server (e.g. co4hook). Its argument string is the remainder of the URL passed to the script. It is formatted as "<keyword>/<rests>". If the hook function does not recognise <keyword>, it returns 0, otherwise it takes the action corresponding to <rests>, then returns 1;
• knowledgeHome: a string "<keyword>/<orders>", that the hook function will recognise, to display the content the repository.

Co4ServerInit("http://lotse.inrialpes.fr:1080/cgi-bin/co4exemple_server",
					6666,
					co4hook,
					"troeps/home-page");

void Co4ServerLoop()
Prints the initial URL to be browsed, corresponding to CO₄ home page, then loops through CO₄ messages, but also requests from the routing script, answering to them.

void Co4ServerStop()
Stops the loop initiated by Co4ServerStart.

Char *gUrlPrefix
The prefix to be concatenated to the string "/<keyword>/<orders>" to make a valid URL understandable by the routing script first, and then by the hook hook.
For example, the CO₄ home page URL is "gUrlPrefix/CO4/home".

Examples

Two examples are available, one basic, the other using a HTTP server. Both use the same content representation and same content management functions, that can be found in examples/common/knowledge.c. The interest of these examples is mainly to show the use and implementation of the functions of the API presented above.

Basic example

An example of the basic capabilities (no server) is available in examples/basic. This example launches repositories, that will communicate between them, tracing on a window their queries and answers. Some examples correspond to the CO₄ specification examples, the rest demonstrate other aspects of CO₄: use of mail boxes and error management. See the README file and the appendix 3.

Server

An example of server is available in examples/server. This example launches a repository as server, to let a browser communicate with it. The server can be created or waken up, and implements a small hook to perform various actions. See the README file.