boinc/dcapi/doc/tmpl/dc_common.sgml

<!-- ##### SECTION Title ##### -->
Common

<!-- ##### SECTION Short_Description ##### -->
functionality available on both the client and master side.

<!-- ##### SECTION Long_Description ##### -->
<para>
The functions and definitions described below are available at both the
client and master side of DC-API in the same form, but may have a
slightly different meaning.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### SECTION Image ##### -->


<!-- ##### ENUM DC_ErrorCode ##### -->
<para>
Error codes returned by DC-API functions.
</para>

@DC_OK: no error.
@DC_ERR_CONFIG: configuration error (syntax error, illegal or missing values).
@DC_ERR_DATABASE: database error.
@DC_ERR_NOTIMPL: the function is not implemented.
@DC_ERR_UNKNOWN_WU: the work unit is not known to DC-API.
@DC_ERR_TIMEOUT: the operation timed out.
@DC_ERR_BADPARAM: the function was passed illegal parameters.
@DC_ERR_SYSTEM: a system call has failed, check errno for the reason.
@DC_ERR_INTERNAL: an internal error occured in DC-API.

<!-- ##### ENUM DC_GridCapabilities ##### -->
<para>
These flags define the capabilities of the underlying grid system.
</para>

@DC_GC_EXITCODE: the client's exit code is propagated to the master.
@DC_GC_STDOUT: the client's standard output is sent back to the master.
@DC_GC_STDERR: the client's standard error is sent back to the master.
@DC_GC_LOG: infrastructure-specific log files are available.
@DC_GC_SUSPEND: suspending of work units is supported.
@DC_GC_SUBRESULT: subresults are supported.
@DC_GC_MESSAGING: message sending is supported.

<!-- ##### ENUM DC_FileMode ##### -->
<para>
Tells how should DC-API treat physical files passed to it.
</para>

@DC_FILE_REGULAR: the application wishes to continue using the file, so DC-API
	must make an internal copy of it.
@DC_FILE_PERSISTENT: the application guarantees that the file will not change
	and will not be deleted during the lifetime of the application. This
	lets DC-API use symbolic or hard links instead of copying to save space.
@DC_FILE_VOLATILE: the application does not want to use the file in any way in
	the future. DC-API will remove the file when it is no longer needed.
@DC_FILE_REMOTE: the application uses a remote file not physically present.

<!-- ##### MACRO DC_CONFIG_FILE ##### -->
<para>
Default name of the DC-API configuration file.
</para>



<!-- ##### MACRO DC_LABEL_STDOUT ##### -->
<para>
Logical name of the client's standard output used with DC_getResultOutput().
</para>



<!-- ##### MACRO DC_LABEL_STDERR ##### -->
<para>
Logical name of the client's standard error used with DC_getResultOutput().
</para>



<!-- ##### MACRO DC_LABEL_CLIENTLOG ##### -->
<para>
Logical name of the client's ifrastructure log used with DC_getResultOutput().
</para>



<!-- ##### STRUCT DC_PhysicalFile ##### -->
<para>
Describes a physical file.
</para>

@label: logical name of the file as used by the application.
@path: the real path name of the file.
@mode: usage mode of the file.
@physicalfilename: filename to be used in case of Attic files.
@physicalfilehash: MD5 hash and size information of Attic files.

<!-- ##### STRUCT DC_RemoteFile ##### -->
<para>
Describes a physical file.
</para>

@label: logical name of the file as used by the application.
@url: the URL of the file.
@remotefilehash: the MD5 hash of the file.
@remotefilesize: the size of the file.

<!-- ##### FUNCTION DC_getCfgStr ##### -->
<para>
Returns the value belonging to the specified key @name in the configuration file.
</para>

@name: the key to look up.
@Returns: the value belonging to the key or %NULL if it is not defined in the
	config file. The returned value must be deallocated using free() when it is
	no longer needed.


<!-- ##### FUNCTION DC_getCfgInt ##### -->
<para>
Returns the integer value belonging to the specified key @name in the configuration
file. Unit suffixes like 'KB', 'GB' or 'hour' are also allowed.
</para>

@name: the key to look up.
@defaultValue: the default value to return if the key is not defined or its value
	cannot be interpreted as a number.
@Returns: the value belonging to the key or @defaultValue if it is not defined in the
	config file.


<!-- ##### FUNCTION DC_getCfgBool ##### -->
<para>
Returns the boolean value belonging to the specified key @name in the configuration
file.
</para>

@name: the key to look up.
@defaultValue: the default value to return if the key is not defined or its value
	cannot be interpreted as a boolean value.
@Returns: the value belonging to the key or @defaultValue if it is not defined in the
	config file.


<!-- ##### FUNCTION DC_log ##### -->
<para>
Emits a message to the master's log file.
</para>

@level: the severity of the. The level codes defined for the system's syslog()
	function should be used.
@fmt: format of the message, as per printf().
@Varargs: any extra arguments required by @fmt.


<!-- ##### FUNCTION DC_vlog ##### -->
<para>
Emits a message to the master's log file.
</para>

@level: the severity of the. The level codes defined for the system's syslog()
	function should be used.
@fmt: format of the message, as per printf().
@args: any extra arguments required by @fmt.


<!-- ##### FUNCTION DC_getMaxMessageSize ##### -->
<para>
Returns the maximum length of a message that DC_sendMessage() (client side) and
DC_sendWUMessage() (master side) accepts.
</para>

@void: 
@Returns: the maximum allowed message size.


<!-- ##### FUNCTION DC_getMaxSubresults ##### -->
<para>
On the master side, returns the maximum number of sub-result files that can be
specified when creating a new work unit.
</para>
<para>
On the client side, returns the number of sub-results the client is still
allowed to send.
</para>

@void: 
@Returns: the number of sub-results allowed.


<!-- ##### FUNCTION DC_getGridCapabilities ##### -->
<para>
Determines the capabilities of the underlying grid infrastructure.
</para>

@void: 
@Returns: the appropriate #DC_GridCapabilities constants OR'ed together.