Specification of the Application Program Interface



next up previous contents
Next: Vote server Up: Interface module Previous: Interface module

Specification of the Application Program Interface

This section defines the application program interface (API) exported by the interface module. The API provides a structured way for the news reader program to communicate with the interface module and consists of two main parts. The first part deals with how the news reader casts votes for articles, and the second part deals with how the news reader gains access to the collected information for an article. A specification for the procedures in the API is given in table gif. The structure which represents a vote is described in table gif.

  
Table: Specification of the API to the interface module.

  
Table: Structure of vote_t record.

Casting a vote requires only that the news reader provide the interface with the information required to create the vote: the name of the newsgroup in which the article appears, the message-id contained in the article, and the user's evaluation of the article. Before exiting, the news reader must call the procedure collab_send_off_votes() to actually send the votes to the collaborative system. If the news reader provides a file name as an argument to collab_send_off_votes(), any votes not cast anonymously will be written to that file. The effective uid of the news reader program will need to have read/write privileges on the file.

Before retrieving vote information from the collaborative system, the news reader client must first set up the list of sources (eg: vote files and/or a vote server) that should be searched for votes. The collab_add_source() and collab_remove_source() routines are provided for this purpose. The strings passed in as source names should be the URLs of the vote files or vote servers. The format of these URLs was discussed earlier.

Once a list of sources has been set, a string containing the names of all the newsgroups which have votes in them can be obtained by calling collab_available_groups(). The aggregated votes for the articles in a newsgroup can be obtained by calling collab_get_votes_for_group(). This will return a linked list of vote_t structures (see table gif) each of which contains the vote information for an article. The vote information tells the number of terrible, ok, good, and great votes the article received. The linked list of vote_t structures should be destroyed when it is no longer needed by calling collab_destroy_votes(). Note that collab_destroy_votes() does not actually remove the votes from the vote source they were drawn from - this process will be discussed later in section gif.



next up previous contents
Next: Vote server Up: Interface module Previous: Interface module



David A. Maltz (dmaltz@cs.cmu.edu)