<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<title>Error reporting</title>
<link href="doxygen.css" rel="stylesheet" type="text/css">
</head><body>
<!-- Generated by Doxygen 1.2.15 -->
<center>
<a class="qindex" href="index.html">Main Page</a> <a class="qindex" href="modules.html">Modules</a> <a class="qindex" href="annotated.html">Data Structures</a> <a class="qindex" href="files.html">File List</a> <a class="qindex" href="functions.html">Data Fields</a> <a class="qindex" href="pages.html">Related Pages</a> </center>
<hr><h1>Error reporting<br>
<small>
[<a class="el" href="group__DBus.html">D-BUS message system public API</a>]</small>
</h1>Error reporting.
<a href="#_details">More...</a><table border=0 cellpadding=0 cellspacing=0>
<tr><td colspan=2><br><h2>Functions</h2></td></tr>
<tr><td nowrap align=right valign=top>void </td><td valign=bottom><a class="el" href="group__DBusErrors.html#a0">dbus_error_init</a> (<a class="el" href="structDBusError.html">DBusError</a> *error)</td></tr>
<tr><td> </td><td><font size=-1><em>Initializes a <a class="el" href="structDBusError.html">DBusError</a> structure.</em> <a href="#a0">More...</a><em></em></font><br><br></td></tr>
<tr><td nowrap align=right valign=top>void </td><td valign=bottom><a class="el" href="group__DBusErrors.html#a1">dbus_error_free</a> (<a class="el" href="structDBusError.html">DBusError</a> *error)</td></tr>
<tr><td> </td><td><font size=-1><em>Frees an error that's been set (or just initialized), then reinitializes the error as in <a class="el" href="group__DBusErrors.html#a0">dbus_error_init</a>().</em> <a href="#a1">More...</a><em></em></font><br><br></td></tr>
<tr><td nowrap align=right valign=top>void </td><td valign=bottom><a class="el" href="group__DBusErrors.html#a2">dbus_set_error_const</a> (<a class="el" href="structDBusError.html">DBusError</a> *error, const char *name, const char *message)</td></tr>
<tr><td> </td><td><font size=-1><em>Assigns an error name and message to a <a class="el" href="structDBusError.html">DBusError</a>.</em> <a href="#a2">More...</a><em></em></font><br><br></td></tr>
<tr><td nowrap align=right valign=top>void </td><td valign=bottom><a class="el" href="group__DBusErrors.html#a3">dbus_move_error</a> (<a class="el" href="structDBusError.html">DBusError</a> *src, <a class="el" href="structDBusError.html">DBusError</a> *dest)</td></tr>
<tr><td> </td><td><font size=-1><em>Moves an error src into dest, freeing src and overwriting dest.</em> <a href="#a3">More...</a><em></em></font><br><br></td></tr>
<tr><td nowrap align=right valign=top><a class="el" href="group__DBusTypes.html#a2">dbus_bool_t</a> </td><td valign=bottom><a class="el" href="group__DBusErrors.html#a4">dbus_error_has_name</a> (const <a class="el" href="structDBusError.html">DBusError</a> *error, const char *name)</td></tr>
<tr><td> </td><td><font size=-1><em>Checks whether the error is set and has the given name.</em> <a href="#a4">More...</a><em></em></font><br><br></td></tr>
<tr><td nowrap align=right valign=top><a class="el" href="group__DBusTypes.html#a2">dbus_bool_t</a> </td><td valign=bottom><a class="el" href="group__DBusErrors.html#a5">dbus_error_is_set</a> (const <a class="el" href="structDBusError.html">DBusError</a> *error)</td></tr>
<tr><td> </td><td><font size=-1><em>Checks whether an error occurred (the error is set).</em> <a href="#a5">More...</a><em></em></font><br><br></td></tr>
<tr><td nowrap align=right valign=top>void </td><td valign=bottom><a class="el" href="group__DBusErrors.html#a6">dbus_set_error</a> (<a class="el" href="structDBusError.html">DBusError</a> *error, const char *name, const char *format,...)</td></tr>
<tr><td> </td><td><font size=-1><em>Assigns an error name and message to a <a class="el" href="structDBusError.html">DBusError</a>.</em> <a href="#a6">More...</a><em></em></font><br><br></td></tr>
</table>
<hr><a name="_details"></a><h2>Detailed Description</h2>
Error reporting.
<p>
<p>
Types and functions related to reporting errors.
<p>
In essence D-BUS error reporting works as follows:
<p>
<div class="fragment"><pre> <a class="code" href="structDBusError.html">DBusError</a> error;
dbus_error_init (&error);
dbus_some_function (arg1, arg2, &error);
<font class="keywordflow">if</font> (dbus_error_is_set (&error))
{
fprintf (stderr, <font class="stringliteral">"an error occurred: %s\n"</font>, error.<a class="code" href="structDBusError.html#m1">message</a>);
dbus_error_free (&error);
}
</pre></div>
<p>
There are some rules. An error passed to a D-BUS function must always be unset; you can't pass in an error that's already set. If a function has a return code indicating whether an error occurred, and also a DBusError parameter, then the error will always be set if and only if the return code indicates an error occurred. i.e. the return code and the error are never going to disagree.
<p>
An error only needs to be freed if it's been set, not if it's merely been initialized.
<p>
You can check the specific error that occurred using <a class="el" href="group__DBusErrors.html#a4">dbus_error_has_name</a>(). <hr><h2>Function Documentation</h2>
<a name="a1" doxytag="dbus-errors.c::dbus_error_free"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
<tr>
<td class="md">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td class="md" nowrap valign="top"> void dbus_error_free </td>
<td class="md" valign="top">( </td>
<td class="md" nowrap valign="top"><a class="el" href="structDBusError.html">DBusError</a> * </td>
<td class="mdname1" valign="top" nowrap> <em>error</em> </td>
<td class="md" valign="top">) </td>
<td class="md" nowrap></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
<tr>
<td>
</td>
<td>
<p>
Frees an error that's been set (or just initialized), then reinitializes the error as in <a class="el" href="group__DBusErrors.html#a0">dbus_error_init</a>().
<p>
<dl compact><dt><b>
Parameters: </b><dd>
<table border=0 cellspacing=2 cellpadding=0>
<tr><td valign=top><em>error</em> </td><td>
memory where the error is stored. </td></tr>
</table>
</dl>
<p>
Definition at line <a class="el" href="dbus-errors_8c-source.html#l00173">173</a> of file <a class="el" href="dbus-errors_8c-source.html">dbus-errors.c</a>.
<p>
References <a class="el" href="dbus-errors_8c-source.html#l00045">DBusRealError::const_message</a>, and <a class="el" href="dbus-errors_8c-source.html#l00043">DBusRealError::message</a>. </td>
</tr>
</table>
<a name="a4" doxytag="dbus-errors.c::dbus_error_has_name"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
<tr>
<td class="md">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td class="md" nowrap valign="top"> <a class="el" href="group__DBusTypes.html#a2">dbus_bool_t</a> dbus_error_has_name </td>
<td class="md" valign="top">( </td>
<td class="md" nowrap valign="top">const <a class="el" href="structDBusError.html">DBusError</a> * </td>
<td class="mdname" nowrap> <em>error</em>, </td>
</tr>
<tr>
<td></td>
<td></td>
<td class="md" nowrap>const char * </td>
<td class="mdname" nowrap> <em>name</em></td>
</tr>
<tr>
<td></td>
<td class="md">) </td>
<td class="md" colspan="2"></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
<tr>
<td>
</td>
<td>
<p>
Checks whether the error is set and has the given name.
<p>
<dl compact><dt><b>
Parameters: </b><dd>
<table border=0 cellspacing=2 cellpadding=0>
<tr><td valign=top><em>error</em> </td><td>
the error </td></tr>
<tr><td valign=top><em>name</em> </td><td>
the name </td></tr>
</table>
</dl><dl compact><dt><b>
Returns: </b><dd>
<a class="el" href="group__DBusMacros.html#a2">TRUE</a> if the given named error occurred </dl>
<p>
Definition at line <a class="el" href="dbus-errors_8c-source.html#l00259">259</a> of file <a class="el" href="dbus-errors_8c-source.html">dbus-errors.c</a>.
<p>
References <a class="el" href="dbus-errors_8h-source.html#l00044">DBusError::message</a>, and <a class="el" href="dbus-errors_8h-source.html#l00043">DBusError::name</a>. </td>
</tr>
</table>
<a name="a0" doxytag="dbus-errors.c::dbus_error_init"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
<tr>
<td class="md">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td class="md" nowrap valign="top"> void dbus_error_init </td>
<td class="md" valign="top">( </td>
<td class="md" nowrap valign="top"><a class="el" href="structDBusError.html">DBusError</a> * </td>
<td class="mdname1" valign="top" nowrap> <em>error</em> </td>
<td class="md" valign="top">) </td>
<td class="md" nowrap></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
<tr>
<td>
</td>
<td>
<p>
Initializes a <a class="el" href="structDBusError.html">DBusError</a> structure.
<p>
Does not allocate any memory; the error only needs to be freed if it is set at some point.<dl compact><dt><b>
Parameters: </b><dd>
<table border=0 cellspacing=2 cellpadding=0>
<tr><td valign=top><em>error</em> </td><td>
the <a class="el" href="structDBusError.html">DBusError</a>. </td></tr>
</table>
</dl>
<p>
Definition at line <a class="el" href="dbus-errors_8c-source.html#l00150">150</a> of file <a class="el" href="dbus-errors_8c-source.html">dbus-errors.c</a>.
<p>
References <a class="el" href="dbus-errors_8c-source.html#l00045">DBusRealError::const_message</a>, <a class="el" href="dbus-errors_8c-source.html#l00043">DBusRealError::message</a>, and <a class="el" href="dbus-errors_8c-source.html#l00042">DBusRealError::name</a>. </td>
</tr>
</table>
<a name="a5" doxytag="dbus-errors.c::dbus_error_is_set"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
<tr>
<td class="md">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td class="md" nowrap valign="top"> <a class="el" href="group__DBusTypes.html#a2">dbus_bool_t</a> dbus_error_is_set </td>
<td class="md" valign="top">( </td>
<td class="md" nowrap valign="top">const <a class="el" href="structDBusError.html">DBusError</a> * </td>
<td class="mdname1" valign="top" nowrap> <em>error</em> </td>
<td class="md" valign="top">) </td>
<td class="md" nowrap></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
<tr>
<td>
</td>
<td>
<p>
Checks whether an error occurred (the error is set).
<p>
<dl compact><dt><b>
Parameters: </b><dd>
<table border=0 cellspacing=2 cellpadding=0>
<tr><td valign=top><em>error</em> </td><td>
the error object </td></tr>
</table>
</dl><dl compact><dt><b>
Returns: </b><dd>
<a class="el" href="group__DBusMacros.html#a2">TRUE</a> if an error occurred </dl>
<p>
Definition at line <a class="el" href="dbus-errors_8c-source.html#l00286">286</a> of file <a class="el" href="dbus-errors_8c-source.html">dbus-errors.c</a>.
<p>
References <a class="el" href="dbus-errors_8h-source.html#l00044">DBusError::message</a>, and <a class="el" href="dbus-errors_8h-source.html#l00043">DBusError::name</a>. </td>
</tr>
</table>
<a name="a3" doxytag="dbus-errors.c::dbus_move_error"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
<tr>
<td class="md">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td class="md" nowrap valign="top"> void dbus_move_error </td>
<td class="md" valign="top">( </td>
<td class="md" nowrap valign="top"><a class="el" href="structDBusError.html">DBusError</a> * </td>
<td class="mdname" nowrap> <em>src</em>, </td>
</tr>
<tr>
<td></td>
<td></td>
<td class="md" nowrap><a class="el" href="structDBusError.html">DBusError</a> * </td>
<td class="mdname" nowrap> <em>dest</em></td>
</tr>
<tr>
<td></td>
<td class="md">) </td>
<td class="md" colspan="2"></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
<tr>
<td>
</td>
<td>
<p>
Moves an error src into dest, freeing src and overwriting dest.
<p>
Both src and dest must be initialized. src is reinitialized to an empty error. dest may not contain an existing error. If the destination is <a class="el" href="group__DBusMacros.html#a4">NULL</a>, just frees and reinits the source error.<dl compact><dt><b>
Parameters: </b><dd>
<table border=0 cellspacing=2 cellpadding=0>
<tr><td valign=top><em>src</em> </td><td>
the source error </td></tr>
<tr><td valign=top><em>dest</em> </td><td>
the destination error or <a class="el" href="group__DBusMacros.html#a4">NULL</a> </td></tr>
</table>
</dl>
<p>
Definition at line <a class="el" href="dbus-errors_8c-source.html#l00236">236</a> of file <a class="el" href="dbus-errors_8c-source.html">dbus-errors.c</a>. </td>
</tr>
</table>
<a name="a6" doxytag="dbus-errors.c::dbus_set_error"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
<tr>
<td class="md">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td class="md" nowrap valign="top"> void dbus_set_error </td>
<td class="md" valign="top">( </td>
<td class="md" nowrap valign="top"><a class="el" href="structDBusError.html">DBusError</a> * </td>
<td class="mdname" nowrap> <em>error</em>, </td>
</tr>
<tr>
<td></td>
<td></td>
<td class="md" nowrap>const char * </td>
<td class="mdname" nowrap> <em>name</em>, </td>
</tr>
<tr>
<td></td>
<td></td>
<td class="md" nowrap>const char * </td>
<td class="mdname" nowrap> <em>format</em>, </td>
</tr>
<tr>
<td></td>
<td></td>
<td class="md" nowrap>... </td>
<td class="mdname" nowrap> </td>
</tr>
<tr>
<td></td>
<td class="md">) </td>
<td class="md" colspan="2"></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
<tr>
<td>
</td>
<td>
<p>
Assigns an error name and message to a <a class="el" href="structDBusError.html">DBusError</a>.
<p>
Does nothing if error is <a class="el" href="group__DBusMacros.html#a4">NULL</a>.
<p>
The format may be NULL, which means a default message will be deduced from the name. If the error name is unknown to D-BUS the default message will be totally useless, though.
<p>
If no memory can be allocated for the error message, an out-of-memory error message will be set instead.
<p>
<p>
<dl compact><dt><b>
<a class="el" href="todo.html#_todo000020">Todo: </a></b><dd>
should be called dbus_error_set()</dl><dl compact><dt><b>
Parameters: </b><dd>
<table border=0 cellspacing=2 cellpadding=0>
<tr><td valign=top><em>error</em> </td><td>
the error. </td></tr>
<tr><td valign=top><em>name</em> </td><td>
the error name (not copied!!!) </td></tr>
<tr><td valign=top><em>format</em> </td><td>
printf-style format string. </td></tr>
</table>
</dl>
<p>
Definition at line <a class="el" href="dbus-errors_8c-source.html#l00312">312</a> of file <a class="el" href="dbus-errors_8c-source.html">dbus-errors.c</a>.
<p>
References <a class="el" href="dbus-errors_8c-source.html#l00045">DBusRealError::const_message</a>, <a class="el" href="dbus-errors_8h-source.html#l00044">DBusError::message</a>, <a class="el" href="dbus-errors_8c-source.html#l00043">DBusRealError::message</a>, <a class="el" href="dbus-errors_8h-source.html#l00043">DBusError::name</a>, and <a class="el" href="dbus-errors_8c-source.html#l00042">DBusRealError::name</a>. </td>
</tr>
</table>
<a name="a2" doxytag="dbus-errors.c::dbus_set_error_const"></a><p>
<table width="100%" cellpadding="2" cellspacing="0" border="0">
<tr>
<td class="md">
<table cellpadding="0" cellspacing="0" border="0">
<tr>
<td class="md" nowrap valign="top"> void dbus_set_error_const </td>
<td class="md" valign="top">( </td>
<td class="md" nowrap valign="top"><a class="el" href="structDBusError.html">DBusError</a> * </td>
<td class="mdname" nowrap> <em>error</em>, </td>
</tr>
<tr>
<td></td>
<td></td>
<td class="md" nowrap>const char * </td>
<td class="mdname" nowrap> <em>name</em>, </td>
</tr>
<tr>
<td></td>
<td></td>
<td class="md" nowrap>const char * </td>
<td class="mdname" nowrap> <em>message</em></td>
</tr>
<tr>
<td></td>
<td class="md">) </td>
<td class="md" colspan="2"></td>
</tr>
</table>
</td>
</tr>
</table>
<table cellspacing=5 cellpadding=0 border=0>
<tr>
<td>
</td>
<td>
<p>
Assigns an error name and message to a <a class="el" href="structDBusError.html">DBusError</a>.
<p>
Does nothing if error is <a class="el" href="group__DBusMacros.html#a4">NULL</a>. The message may be NULL, which means a default message will be deduced from the name. If the error name is unknown to D-BUS the default message will be totally useless, though.
<p>
<p>
<dl compact><dt><b>
<a class="el" href="todo.html#_todo000019">Todo: </a></b><dd>
should be called dbus_error_set_const()</dl><dl compact><dt><b>
Parameters: </b><dd>
<table border=0 cellspacing=2 cellpadding=0>
<tr><td valign=top><em>error</em> </td><td>
the error. </td></tr>
<tr><td valign=top><em>name</em> </td><td>
the error name (not copied!!!) </td></tr>
<tr><td valign=top><em>message</em> </td><td>
the error message (not copied!!!) </td></tr>
</table>
</dl>
<p>
Definition at line <a class="el" href="dbus-errors_8c-source.html#l00200">200</a> of file <a class="el" href="dbus-errors_8c-source.html">dbus-errors.c</a>.
<p>
References <a class="el" href="dbus-errors_8c-source.html#l00045">DBusRealError::const_message</a>, <a class="el" href="dbus-errors_8h-source.html#l00044">DBusError::message</a>, <a class="el" href="dbus-errors_8c-source.html#l00043">DBusRealError::message</a>, <a class="el" href="dbus-errors_8h-source.html#l00043">DBusError::name</a>, and <a class="el" href="dbus-errors_8c-source.html#l00042">DBusRealError::name</a>. </td>
</tr>
</table>
<hr><address align="right"><small>Generated on Wed Jun 9 05:01:27 2004 for D-BUS by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border=0
width=110 height=53></a>1.2.15 </small></address>
</body>
</html>
distrib
>
Mandriva
>
2007.0
>
x86_64
>
media
>
main-release
>
by-pkgid
>
926d2d1e3111287cee1b0a4fad4fb4f6
>
files
>
171
