[[PageOutline]]
= Trickle message API =
	
The interface for [TrickleMessages 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 ==

=== Handling trickle-up messages ===

To handle trickle-up messages, use a 'trickle_handler' daemon.
This is a program, based on sched/trickle_handler.cpp, linked with functions

{{{
int handle_trickle_init(int argc, char** argv);     // initialize
int handle_trickle(MSG_FROM_HOST&);                 // handle a trickle message

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.
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 [ProjectDaemons project configuration file].

By default, a trickle handler daemon enumerates msg_from_host records with handled==0,
and when done sets handled=1.
If you need multiple stages of trickle handling,
you can do so by assigning '''handled_enum''' and '''handled_set''' in handle_trickle_init().
For example, by setting these to 1 and 2 respectively you can add a 2nd stage of handling.


=== Sending trickle-down messages ===

To 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, include

{{{
<msg_to_host/>
}}}

in your [ProjectOptions#Clientcontrol configuration] (config.xml) file.

== Purging trickle messages ==

If you use either type of trickle message, you should include
{{{
<task>
  <output>purge_trickles.out</output>
  <cmd>run_in_ops purge_trickles.php</cmd>
  <period>24 hours</period>
</task>
}}}

in your [ProjectOptions#Clientcontrol configuration] (config.xml) file,
to delete unneeded trickle-related records from your database.
It you use multiple stages of trickle-up handling, use
{{{
purge_trickles.php msg_from_host 2
}}}
or whatever the final value of "handled" is.

== Replicated trickle-up messages ==

You can arrange to have trickle-up messages sent not only the the project's scheduler,
but to other schedulers as well.
To do this, including the following in your gui_urls.xml file:

{{{
<trickle_up_urls>
    <url>http://a.b.edu/test2_cgi/cgi</url>
    [ ... ]
</trickle_up_urls>
}}}

The messages sent to these trickle-up handlers
are abbreviated versions of scheduler RPC requests.

This works only with 6.13.5+ clients.