Changes between Initial Version and Version 1 of TrickleApi

Timestamp:

Apr 19, 2007, 8:54:06 PM (17 years ago)

Author:

KSMarksPsych

Comment:

--

TrickleApi

@@ +1 @@
+= Trickle message API =
+        
+The interface for [http://boinc.berkeley.edu/trickle.php trickle messages] includes both client-side and server-side components.
+
+== Client-side API ==
+
+To send a trickle-up message, call
+
+{{{
+int boinc_send_trickle_up(char* variety, char* text)
+}}}
+
+To receive a trickle-down message, call
+
+{{{
+int boinc_receive_trickle_down(char* buf, int len)
+}}}
+
+This returns true (nonzero) if there was a message.
+
+== Server-side API ==
+
+To handle trickle-up messages, use a 'trickle_handler' daemon. This is a program, based on sched/trickle_handler.C, linked with a function
+
+{{{
+int handle_trickle(MSG_FROM_HOST&);
+
+struct MSG_FROM_HOST {
+    int create_time;
+    int hostid;
+    char variety[256];              // project-defined; what kind of msg
+    char xml[MSG_FROM_HOST_BLOB_SIZE];
+};
+}}}
+
+This function should return zero if the message was handled successfully; otherwise it will be retried later. The 'hostid' field identifies the host from which the message was sent. The daemon must be passed a '-variety X' command-line argument, telling it what kind of messages to handle. The daemon should be specified in the [http://boinc.berkeley.edu/project_daemons.php project configuration file].
+
+To send send trickle-down messages (from a trickle handler daemon or other program) you must insert a record in the 'msg_to_host' table. From C/C++, this is done as follows:
+
+{{{
+DB_MSG_TO_HOST mth;
+
+mth.clear();
+mth.create_time = time(0);
+mth.hostid = hostid;
+sprintf(mth.xml,
+    "<trickle_down>\n"
+    "   <result_name>%s</result_name>\n"
+    "   ...\n"
+    "</trickle_down>\n",
+    ...
+);
+retval = mth.insert();
+}}}
+
+To send trickle-down messages, a project must include the line
+
+{{{
+<msg_to_host/>
+}}}
+
+in the [http://boinc.berkeley.edu/configuration.php configuration] (config.xml) file.