The BOINC Application Programming Interface (API)

The BOINC API is a library of C++ functions. All the functions return an integer error code; zero indicates success.

Initialization and termination

An application must call 
    int boinc_init(bool is_main_program, char* app_preferences)
before calling other BOINC functions or doing I/O. is_main_program indicates whether the program is the application's main program (normally true - see below). The user's application-specific preferences, if any, are returned in app_preferences. When the application has completed successfully it must call 
    int boinc_finish();
before exiting. An application that encounters a fatal error must call 
    void exit(int error);

Resolving file names

Applications that use named input or output files must call 
    int boinc_resolve_link(char *logical_name, char *physical_name);
to convert logical file names to physical names. For example, instead of 
    f = fopen("my_file", "r");

the application might use 

    char resolved_name[256];
    retval = boinc_resolve_link("my_file", resolved_name);
    if (retval) fail("can't resolve filename");
    f = fopen(resolved_name, "r");
boinc_resolve_link() doesn't need to be used for temporary files.

Checkpointing

Computations that use a significant amount of time per work unit may want to periodically write the current state of the computation to disk. This is known as checkpointing. The state file must include everything required to start the computation again at the same place it was checkpointed. On startup, the application reads the state file to determine where to begin computation. If the BOINC client quits or exits, the computation can be restarted from the most recent checkpoint.

Do use checkpoint, an application should write to output and state files using the MFILE class. 

class MFILE {
public:
    int open(char* path, char* mode);
    int _putchar(char);
    int puts(char*);
    int printf(char* format, ...);
    size_t write(const void* buf, size_t count);
    int close();
    int flush();
};
MFILE buffers data in memory and writes to disk only on flush() or close(). This lets you write output files and state files more or less atomically. Frequency of checkpointing is a user preference (e.g. laptop users might want to checkpoint infrequently). An application must call 
bool time_to_checkpoint();
whenever it reaches a point where it is able to checkpoint. If this returns true, the application should write the state file and flush all output files, then call 
void checkpoint_completed();

Fraction done

The core client GUI displays the percent done of workunits in progress. To keep this display current, an application should periodically call 
   boinc_percent_done(double fraction_done);
The fraction_done argument is a rough estimate of the workunit percentage complete.

Multi-program applications

Some applications consist of multiple programs: a main program that acts as coordinator, and one or more subsidiary programs. Each program should use the BOINC API as described above, using the appropriate argument to boinc_init().

For checkpointing, each program has its own state file; the state file of the coordinator program records which subsidiary program was last active.

To correctly implement percent done, the main program should pass information to subsidiary programs (perhaps as command-line arguments) the starting and ending fractions for that program.

Implementation

Application are executed in separate "sandbox" directories, allowing them to create and use temporary files without concern about name conflicts. Input and output files are kept outside the sandbox. The mappings from virtual to physical filenames are done using "symbolic link" files in the sandbox directory. The name of such a file is the virtual name, and it contains an XML tag with the physical name. This scheme is necessary because of the lack of filesystem links in Windows.

Communication between the core client and applications is done through XML files in the sandbox directory. Several files are used.

Files created by the core client, read by the app:

Files created by the app, read by the core client:

The implementation of the API uses timers