| Current File : //usr/share/doc/dbus/api/group__DBusBus.html |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>D-Bus: Message bus APIs</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">D-Bus
 <span id="projectnumber">1.8.20</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- Generated by Doxygen 1.7.6.1 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div>
<div class="header">
<div class="summary">
<a href="#func-members">Functions</a> </div>
<div class="headertitle">
<div class="title">Message bus APIs</div> </div>
<div class="ingroups"><a class="el" href="group__DBus.html">D-Bus low-level public API</a></div></div><!--header-->
<div class="contents">
<p>Functions for communicating with the message bus.
<a href="#details">More...</a></p>
<table class="memberdecls">
<tr><td colspan="2"><h2><a name="func-members"></a>
Functions</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="structDBusConnection.html">DBusConnection</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__DBusBus.html#ga77ba5250adb84620f16007e1b023cf26">dbus_bus_get</a> (<a class="el" href="group__DBusShared.html#ga980320deb96476bee7555edcdebc3528">DBusBusType</a> type, <a class="el" href="structDBusError.html">DBusError</a> *error)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Connects to a bus daemon and registers the client with it. <a href="#ga77ba5250adb84620f16007e1b023cf26"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="structDBusConnection.html">DBusConnection</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__DBusBus.html#ga9c62186f19cf3bd3c7c604bdcefb4e09">dbus_bus_get_private</a> (<a class="el" href="group__DBusShared.html#ga980320deb96476bee7555edcdebc3528">DBusBusType</a> type, <a class="el" href="structDBusError.html">DBusError</a> *error)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Connects to a bus daemon and registers the client with it as with <a class="el" href="group__DBusBus.html#ga0c21cf74d05c0bd8003846b56a588a4b" title="Registers a connection with the bus.">dbus_bus_register()</a>. <a href="#ga9c62186f19cf3bd3c7c604bdcefb4e09"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__DBusTypes.html#ga39c9cb0f3a2a8ad6f55cc4855d035349">dbus_bool_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="group__DBusBus.html#ga0c21cf74d05c0bd8003846b56a588a4b">dbus_bus_register</a> (<a class="el" href="structDBusConnection.html">DBusConnection</a> *connection, <a class="el" href="structDBusError.html">DBusError</a> *error)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Registers a connection with the bus. <a href="#ga0c21cf74d05c0bd8003846b56a588a4b"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__DBusTypes.html#ga39c9cb0f3a2a8ad6f55cc4855d035349">dbus_bool_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="group__DBusBus.html#ga0366177076e88bf37771341f32b0551c">dbus_bus_set_unique_name</a> (<a class="el" href="structDBusConnection.html">DBusConnection</a> *connection, const char *unique_name)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Sets the unique name of the connection, as assigned by the message bus. <a href="#ga0366177076e88bf37771341f32b0551c"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">const char * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__DBusBus.html#ga8c10339a1e62f6a2e5752d9c2270d37b">dbus_bus_get_unique_name</a> (<a class="el" href="structDBusConnection.html">DBusConnection</a> *connection)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Gets the unique name of the connection as assigned by the message bus. <a href="#ga8c10339a1e62f6a2e5752d9c2270d37b"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">unsigned long </td><td class="memItemRight" valign="bottom"><a class="el" href="group__DBusBus.html#ga24d782c710f3d82caf1b1ed582dcf474">dbus_bus_get_unix_user</a> (<a class="el" href="structDBusConnection.html">DBusConnection</a> *connection, const char *name, <a class="el" href="structDBusError.html">DBusError</a> *error)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Asks the bus to return the UID the named connection authenticated as, if any. <a href="#ga24d782c710f3d82caf1b1ed582dcf474"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">char * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__DBusBus.html#ga18314500e7f6890a79bddbeace5df5f9">dbus_bus_get_id</a> (<a class="el" href="structDBusConnection.html">DBusConnection</a> *connection, <a class="el" href="structDBusError.html">DBusError</a> *error)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Asks the bus to return its globally unique ID, as described in the D-Bus specification. <a href="#ga18314500e7f6890a79bddbeace5df5f9"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__DBusBus.html#ga8a9024c78c4ea89b6271f19dbc7861b2">dbus_bus_request_name</a> (<a class="el" href="structDBusConnection.html">DBusConnection</a> *connection, const char *name, unsigned int flags, <a class="el" href="structDBusError.html">DBusError</a> *error)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Asks the bus to assign the given name to this connection by invoking the RequestName method on the bus. <a href="#ga8a9024c78c4ea89b6271f19dbc7861b2"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__DBusBus.html#gaa4aa5ebe51cdbe8c0651609fc72e841a">dbus_bus_release_name</a> (<a class="el" href="structDBusConnection.html">DBusConnection</a> *connection, const char *name, <a class="el" href="structDBusError.html">DBusError</a> *error)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Asks the bus to unassign the given name from this connection by invoking the ReleaseName method on the bus. <a href="#gaa4aa5ebe51cdbe8c0651609fc72e841a"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__DBusTypes.html#ga39c9cb0f3a2a8ad6f55cc4855d035349">dbus_bool_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="group__DBusBus.html#ga5331b172dd8ed00eec130e894c5c2a0b">dbus_bus_name_has_owner</a> (<a class="el" href="structDBusConnection.html">DBusConnection</a> *connection, const char *name, <a class="el" href="structDBusError.html">DBusError</a> *error)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Asks the bus whether a certain name has an owner. <a href="#ga5331b172dd8ed00eec130e894c5c2a0b"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__DBusTypes.html#ga39c9cb0f3a2a8ad6f55cc4855d035349">dbus_bool_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="group__DBusBus.html#ga81d303bf29d7c97ad4690ce35071b090">dbus_bus_start_service_by_name</a> (<a class="el" href="structDBusConnection.html">DBusConnection</a> *connection, const char *name, <a class="el" href="group__DBusTypes.html#gaf513803b030613a669cc7ef199f90a8b">dbus_uint32_t</a> flags, <a class="el" href="group__DBusTypes.html#gaf513803b030613a669cc7ef199f90a8b">dbus_uint32_t</a> *result, <a class="el" href="structDBusError.html">DBusError</a> *error)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Starts a service that will request ownership of the given name. <a href="#ga81d303bf29d7c97ad4690ce35071b090"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__DBusBus.html#ga4eb6401ba014da3dbe3dc4e2a8e5b3ef">dbus_bus_add_match</a> (<a class="el" href="structDBusConnection.html">DBusConnection</a> *connection, const char *rule, <a class="el" href="structDBusError.html">DBusError</a> *error)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Adds a match rule to match messages going through the message bus. <a href="#ga4eb6401ba014da3dbe3dc4e2a8e5b3ef"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__DBusBus.html#ga6e6b98e19fa4400de7ef99c27b866b99">dbus_bus_remove_match</a> (<a class="el" href="structDBusConnection.html">DBusConnection</a> *connection, const char *rule, <a class="el" href="structDBusError.html">DBusError</a> *error)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Removes a previously-added match rule "by value" (the most recently-added identical rule gets removed). <a href="#ga6e6b98e19fa4400de7ef99c27b866b99"></a><br/></td></tr>
</table>
<hr/><a name="details" id="details"></a><h2>Detailed Description</h2>
<p>Functions for communicating with the message bus. </p>
<p><a class="el" href="group__DBusBus.html#ga77ba5250adb84620f16007e1b023cf26" title="Connects to a bus daemon and registers the client with it.">dbus_bus_get()</a> allows all modules and libraries in a given process to share the same connection to the bus daemon by storing the connection globally.</p>
<p>All other functions in this module are just convenience functions; most of them invoke methods on the bus daemon, by sending method call messages to <a class="el" href="group__DBusShared.html#ga9e017e829e575bdc5c554fd4d07d7355" title="The bus name used to talk to the bus itself.">DBUS_SERVICE_DBUS</a>. These convenience functions often make blocking method calls. If you don't want to block, you can send the method call messages manually in the same way you would any other method call message.</p>
<p>This module is the only one in libdbus that's specific to communicating with the message bus daemon. The rest of the API can also be used for connecting to another application directly.</p>
<dl class="todo"><dt><b><a class="el" href="todo.html#_todo000006">Todo:</a></b></dt><dd>right now the default address of the system bus is hardcoded, so if you change it in the global config file suddenly you have to set DBUS_SYSTEM_BUS_ADDRESS env variable. Might be nice if the client lib somehow read the config file, or if the bus on startup somehow wrote out its address to a well-known spot, but might also not be worth it. </dd></dl>
<hr/><h2>Function Documentation</h2>
<a class="anchor" id="ga4eb6401ba014da3dbe3dc4e2a8e5b3ef"></a><!-- doxytag: member="dbus-bus.c::dbus_bus_add_match" ref="ga4eb6401ba014da3dbe3dc4e2a8e5b3ef" args="(DBusConnection *connection, const char *rule, DBusError *error)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">DBUS_EXPORT void <a class="el" href="group__DBusBus.html#ga4eb6401ba014da3dbe3dc4e2a8e5b3ef">dbus_bus_add_match</a> </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structDBusConnection.html">DBusConnection</a> * </td>
<td class="paramname"><em>connection</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>rule</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structDBusError.html">DBusError</a> * </td>
<td class="paramname"><em>error</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Adds a match rule to match messages going through the message bus. </p>
<p>The "rule" argument is the string form of a match rule.</p>
<p>If you pass <a class="el" href="group__DBusMacros.html#ga070d2ce7b6bb7e5c05602aa8c308d0c4" title="A null pointer, defined appropriately for C or C++.">NULL</a> for the error, this function will not block; the match thus won't be added until you flush the connection, and if there's an error adding the match you won't find out about it. This is generally acceptable, since the possible errors (including a lack of resources in the bus, the connection having exceeded its quota of active match rules, or the match rule being unparseable) are generally unrecoverable.</p>
<p>If you pass non-<a class="el" href="group__DBusMacros.html#ga070d2ce7b6bb7e5c05602aa8c308d0c4" title="A null pointer, defined appropriately for C or C++.">NULL</a> for the error this function will block until it gets a reply. This may be useful when using match rule keys introduced in recent versions of D-Bus, like 'arg0namespace', to allow the application to fall back to less efficient match rules supported by older versions of the daemon if the running version is not new enough; or when using user-supplied rules rather than rules hard-coded at compile time.</p>
<p>Normal API conventions would have the function return a boolean value indicating whether the error was set, but that would require blocking always to determine the return value.</p>
<p>The AddMatch method is fully documented in the D-Bus specification. For quick reference, the format of the match rules is discussed here, but the specification is the canonical version of this information.</p>
<p>Rules are specified as a string of comma separated key/value pairs. An example is "type='signal',sender='org.freedesktop.DBus', interface='org.freedesktop.DBus',member='Foo', path='/bar/foo',destination=':452345.34'"</p>
<p>Possible keys you can match on are type, sender, interface, member, path, destination and numbered keys to match message args (keys are 'arg0', 'arg1', etc.). Omitting a key from the rule indicates a wildcard match. For instance omitting the member from a match rule but adding a sender would let all messages from that sender through regardless of the member.</p>
<p>Matches are inclusive not exclusive so as long as one rule matches the message will get through. It is important to note this because every time a message is received the application will be paged into memory to process it. This can cause performance problems such as draining batteries on embedded platforms.</p>
<p>If you match message args ('arg0', 'arg1', and so forth) only string arguments will match. That is, arg0='5' means match the string "5" not the integer 5.</p>
<p>Currently there is no way to match against non-string arguments.</p>
<p>A specialised form of wildcard matching on arguments is supported for path-like namespaces. If your argument match has a 'path' suffix (eg: "arg0path='/some/path/'") then it is considered a match if the argument exactly matches the given string or if one of them ends in a '/' and is a prefix of the other.</p>
<p>Matching on interface is tricky because method call messages only optionally specify the interface. If a message omits the interface, then it will NOT match if the rule specifies an interface name. This means match rules on method calls should not usually give an interface.</p>
<p>However, signal messages are required to include the interface so when matching signals usually you should specify the interface in the match rule.</p>
<p>For security reasons, you can match arguments only up to <a class="el" href="group__DBusProtocol.html#gaefeb44421a66e8184d70aae52918b101" title="Max arg number you can match on in a match rule, e.g.">DBUS_MAXIMUM_MATCH_RULE_ARG_NUMBER</a>.</p>
<p>Match rules have a maximum length of <a class="el" href="group__DBusProtocol.html#gaca161f9a67ce5adf617476c1956d4ee1" title="Max length of a match rule string; to keep people from hosing the daemon with some huge rule...">DBUS_MAXIMUM_MATCH_RULE_LENGTH</a> bytes.</p>
<p>Both of these maximums are much higher than you're likely to need, they only exist because the D-Bus bus daemon has fixed limits on all resource usage.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">connection</td><td>connection to the message bus </td></tr>
<tr><td class="paramname">rule</td><td>textual form of match rule </td></tr>
<tr><td class="paramname">error</td><td>location to store any errors </td></tr>
</table>
</dd>
</dl>
<p>Definition at line <a class="el" href="dbus-bus_8c_source.html#l01526">1526</a> of file <a class="el" href="dbus-bus_8c_source.html">dbus-bus.c</a>.</p>
<p>References <a class="el" href="dbus-shared_8h_source.html#l00088">DBUS_INTERFACE_DBUS</a>, <a class="el" href="dbus-message_8c_source.html#l01792">dbus_message_append_args()</a>, <a class="el" href="dbus-message_8c_source.html#l01333">dbus_message_new_method_call()</a>, <a class="el" href="dbus-message_8c_source.html#l01690">dbus_message_unref()</a>, <a class="el" href="dbus-shared_8h_source.html#l00080">DBUS_PATH_DBUS</a>, <a class="el" href="dbus-shared_8h_source.html#l00076">DBUS_SERVICE_DBUS</a>, <a class="el" href="dbus-protocol_8h_source.html#l00060">DBUS_TYPE_INVALID</a>, <a class="el" href="dbus-protocol_8h_source.html#l00102">DBUS_TYPE_STRING</a>, and <a class="el" href="group__DBusMacros.html#ga070d2ce7b6bb7e5c05602aa8c308d0c4">NULL</a>.</p>
</div>
</div>
<a class="anchor" id="ga77ba5250adb84620f16007e1b023cf26"></a><!-- doxytag: member="dbus-bus.c::dbus_bus_get" ref="ga77ba5250adb84620f16007e1b023cf26" args="(DBusBusType type, DBusError *error)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">DBUS_EXPORT <a class="el" href="structDBusConnection.html">DBusConnection</a> * <a class="el" href="group__DBusBus.html#ga77ba5250adb84620f16007e1b023cf26">dbus_bus_get</a> </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__DBusShared.html#ga980320deb96476bee7555edcdebc3528">DBusBusType</a> </td>
<td class="paramname"><em>type</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structDBusError.html">DBusError</a> * </td>
<td class="paramname"><em>error</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Connects to a bus daemon and registers the client with it. </p>
<p>If a connection to the bus already exists, then that connection is returned. The caller of this function owns a reference to the bus.</p>
<p>The caller may NOT call <a class="el" href="group__DBusConnection.html#ga2522ac5075dfe0a1535471f6e045e1ee" title="Closes a private connection, so no further data can be sent or received.">dbus_connection_close()</a> on this connection; see <a class="el" href="group__DBusConnection.html#gacd32f819820266598c6b6847dfddaf9c" title="Gets a connection to a remote address.">dbus_connection_open()</a> and <a class="el" href="group__DBusConnection.html#ga2522ac5075dfe0a1535471f6e045e1ee" title="Closes a private connection, so no further data can be sent or received.">dbus_connection_close()</a> for details on that.</p>
<p>If this function obtains a new connection object never before returned from <a class="el" href="group__DBusBus.html#ga77ba5250adb84620f16007e1b023cf26" title="Connects to a bus daemon and registers the client with it.">dbus_bus_get()</a>, it will call <a class="el" href="group__DBusConnection.html#ga19091beb74f1504b0e862a7ad10e71cd" title="Set whether _exit() should be called when the connection receives a disconnect signal.">dbus_connection_set_exit_on_disconnect()</a>, so the application will exit if the connection closes. You can undo this by calling <a class="el" href="group__DBusConnection.html#ga19091beb74f1504b0e862a7ad10e71cd" title="Set whether _exit() should be called when the connection receives a disconnect signal.">dbus_connection_set_exit_on_disconnect()</a> yourself after you get the connection.</p>
<p><a class="el" href="group__DBusBus.html#ga77ba5250adb84620f16007e1b023cf26" title="Connects to a bus daemon and registers the client with it.">dbus_bus_get()</a> calls <a class="el" href="group__DBusBus.html#ga0c21cf74d05c0bd8003846b56a588a4b" title="Registers a connection with the bus.">dbus_bus_register()</a> for you.</p>
<p>If returning a newly-created connection, this function will block until authentication and bus registration are complete.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">type</td><td>bus type </td></tr>
<tr><td class="paramname">error</td><td>address where an error can be returned. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>a <a class="el" href="structDBusConnection.html" title="Implementation details of DBusConnection.">DBusConnection</a> with new ref or <a class="el" href="group__DBusMacros.html#ga070d2ce7b6bb7e5c05602aa8c308d0c4" title="A null pointer, defined appropriately for C or C++.">NULL</a> on error </dd></dl>
<p>Definition at line <a class="el" href="dbus-bus_8c_source.html#l00558">558</a> of file <a class="el" href="dbus-bus_8c_source.html">dbus-bus.c</a>.</p>
<p>References <a class="el" href="group__DBusMacros.html#gaa93f0eb578d23995850d61f7d61c55c1">FALSE</a>.</p>
</div>
</div>
<a class="anchor" id="ga18314500e7f6890a79bddbeace5df5f9"></a><!-- doxytag: member="dbus-bus.c::dbus_bus_get_id" ref="ga18314500e7f6890a79bddbeace5df5f9" args="(DBusConnection *connection, DBusError *error)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">DBUS_EXPORT char * <a class="el" href="group__DBusBus.html#ga18314500e7f6890a79bddbeace5df5f9">dbus_bus_get_id</a> </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structDBusConnection.html">DBusConnection</a> * </td>
<td class="paramname"><em>connection</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structDBusError.html">DBusError</a> * </td>
<td class="paramname"><em>error</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Asks the bus to return its globally unique ID, as described in the D-Bus specification. </p>
<p>For the session bus, this is useful as a way to uniquely identify each user session. For the system bus, probably the bus ID is not useful; instead, use the machine ID since it's accessible without necessarily connecting to the bus and may be persistent beyond a single bus instance (across reboots for example). See <a class="el" href="group__DBusMisc.html#ga2b21c9a12fea5f92763441c65ccbfcf9" title="Obtains the machine UUID of the machine this process is running on.">dbus_get_local_machine_id()</a>.</p>
<p>In addition to an ID for each bus and an ID for each machine, there is an ID for each address that the bus is listening on; that can be retrieved with <a class="el" href="group__DBusConnection.html#gae6c19e146a37f9de6a06c1617874bed9" title="Gets the ID of the server address we are authenticated to, if this connection is on the client side...">dbus_connection_get_server_id()</a>, though it is probably not very useful.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">connection</td><td>the connection </td></tr>
<tr><td class="paramname">error</td><td>location to store the error </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the bus ID or <a class="el" href="group__DBusMacros.html#ga070d2ce7b6bb7e5c05602aa8c308d0c4" title="A null pointer, defined appropriately for C or C++.">NULL</a> if error is set </dd></dl>
<p>Definition at line <a class="el" href="dbus-bus_8c_source.html#l00948">948</a> of file <a class="el" href="dbus-bus_8c_source.html">dbus-bus.c</a>.</p>
<p>References <a class="el" href="dbus-internals_8c_source.html#l00527">_dbus_strdup()</a>, <a class="el" href="dbus-connection_8c_source.html#l03535">dbus_connection_send_with_reply_and_block()</a>, <a class="el" href="dbus-shared_8h_source.html#l00088">DBUS_INTERFACE_DBUS</a>, <a class="el" href="dbus-message_8c_source.html#l01980">dbus_message_get_args()</a>, <a class="el" href="dbus-message_8c_source.html#l01333">dbus_message_new_method_call()</a>, <a class="el" href="dbus-message_8c_source.html#l01690">dbus_message_unref()</a>, <a class="el" href="dbus-shared_8h_source.html#l00080">DBUS_PATH_DBUS</a>, <a class="el" href="dbus-shared_8h_source.html#l00076">DBUS_SERVICE_DBUS</a>, <a class="el" href="dbus-message_8c_source.html#l03796">dbus_set_error_from_message()</a>, <a class="el" href="dbus-protocol_8h_source.html#l00060">DBUS_TYPE_INVALID</a>, <a class="el" href="dbus-protocol_8h_source.html#l00102">DBUS_TYPE_STRING</a>, and <a class="el" href="group__DBusMacros.html#ga070d2ce7b6bb7e5c05602aa8c308d0c4">NULL</a>.</p>
</div>
</div>
<a class="anchor" id="ga9c62186f19cf3bd3c7c604bdcefb4e09"></a><!-- doxytag: member="dbus-bus.c::dbus_bus_get_private" ref="ga9c62186f19cf3bd3c7c604bdcefb4e09" args="(DBusBusType type, DBusError *error)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">DBUS_EXPORT <a class="el" href="structDBusConnection.html">DBusConnection</a> * <a class="el" href="group__DBusBus.html#ga9c62186f19cf3bd3c7c604bdcefb4e09">dbus_bus_get_private</a> </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__DBusShared.html#ga980320deb96476bee7555edcdebc3528">DBusBusType</a> </td>
<td class="paramname"><em>type</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structDBusError.html">DBusError</a> * </td>
<td class="paramname"><em>error</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Connects to a bus daemon and registers the client with it as with <a class="el" href="group__DBusBus.html#ga0c21cf74d05c0bd8003846b56a588a4b" title="Registers a connection with the bus.">dbus_bus_register()</a>. </p>
<p>Unlike <a class="el" href="group__DBusBus.html#ga77ba5250adb84620f16007e1b023cf26" title="Connects to a bus daemon and registers the client with it.">dbus_bus_get()</a>, always creates a new connection. This connection will not be saved or recycled by libdbus. Caller owns a reference to the bus and must either close it or know it to be closed prior to releasing this reference.</p>
<p>See <a class="el" href="group__DBusConnection.html#ga434e3fc7ee420fd30e2f05e57ff26b1d" title="Opens a new, dedicated connection to a remote address.">dbus_connection_open_private()</a> for more details on when to close and unref this connection.</p>
<p>This function calls <a class="el" href="group__DBusConnection.html#ga19091beb74f1504b0e862a7ad10e71cd" title="Set whether _exit() should be called when the connection receives a disconnect signal.">dbus_connection_set_exit_on_disconnect()</a> on the new connection, so the application will exit if the connection closes. You can undo this by calling <a class="el" href="group__DBusConnection.html#ga19091beb74f1504b0e862a7ad10e71cd" title="Set whether _exit() should be called when the connection receives a disconnect signal.">dbus_connection_set_exit_on_disconnect()</a> yourself after you get the connection.</p>
<p><a class="el" href="group__DBusBus.html#ga9c62186f19cf3bd3c7c604bdcefb4e09" title="Connects to a bus daemon and registers the client with it as with dbus_bus_register().">dbus_bus_get_private()</a> calls <a class="el" href="group__DBusBus.html#ga0c21cf74d05c0bd8003846b56a588a4b" title="Registers a connection with the bus.">dbus_bus_register()</a> for you.</p>
<p>This function will block until authentication and bus registration are complete.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">type</td><td>bus type </td></tr>
<tr><td class="paramname">error</td><td>address where an error can be returned. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>a <a class="el" href="structDBusConnection.html" title="Implementation details of DBusConnection.">DBusConnection</a> with new ref </dd></dl>
<p>Definition at line <a class="el" href="dbus-bus_8c_source.html#l00590">590</a> of file <a class="el" href="dbus-bus_8c_source.html">dbus-bus.c</a>.</p>
<p>References <a class="el" href="group__DBusMacros.html#gaa8cecfc5c5c054d2875c03e77b7be15d">TRUE</a>.</p>
</div>
</div>
<a class="anchor" id="ga8c10339a1e62f6a2e5752d9c2270d37b"></a><!-- doxytag: member="dbus-bus.c::dbus_bus_get_unique_name" ref="ga8c10339a1e62f6a2e5752d9c2270d37b" args="(DBusConnection *connection)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">DBUS_EXPORT const char * <a class="el" href="group__DBusBus.html#ga8c10339a1e62f6a2e5752d9c2270d37b">dbus_bus_get_unique_name</a> </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structDBusConnection.html">DBusConnection</a> * </td>
<td class="paramname"><em>connection</em></td><td>)</td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Gets the unique name of the connection as assigned by the message bus. </p>
<p>Only possible after the connection has been registered with the message bus. All connections returned by <a class="el" href="group__DBusBus.html#ga77ba5250adb84620f16007e1b023cf26" title="Connects to a bus daemon and registers the client with it.">dbus_bus_get()</a> or <a class="el" href="group__DBusBus.html#ga9c62186f19cf3bd3c7c604bdcefb4e09" title="Connects to a bus daemon and registers the client with it as with dbus_bus_register().">dbus_bus_get_private()</a> have been successfully registered.</p>
<p>The name remains valid until the connection is freed, and should not be freed by the caller.</p>
<p>Other than <a class="el" href="group__DBusBus.html#ga77ba5250adb84620f16007e1b023cf26" title="Connects to a bus daemon and registers the client with it.">dbus_bus_get()</a>, there are two ways to set the unique name; one is <a class="el" href="group__DBusBus.html#ga0c21cf74d05c0bd8003846b56a588a4b" title="Registers a connection with the bus.">dbus_bus_register()</a>, the other is <a class="el" href="group__DBusBus.html#ga0366177076e88bf37771341f32b0551c" title="Sets the unique name of the connection, as assigned by the message bus.">dbus_bus_set_unique_name()</a>. You are responsible for calling <a class="el" href="group__DBusBus.html#ga0366177076e88bf37771341f32b0551c" title="Sets the unique name of the connection, as assigned by the message bus.">dbus_bus_set_unique_name()</a> if you register by hand instead of using <a class="el" href="group__DBusBus.html#ga0c21cf74d05c0bd8003846b56a588a4b" title="Registers a connection with the bus.">dbus_bus_register()</a>.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">connection</td><td>the connection </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the unique name or <a class="el" href="group__DBusMacros.html#ga070d2ce7b6bb7e5c05602aa8c308d0c4" title="A null pointer, defined appropriately for C or C++.">NULL</a> on error </dd></dl>
<p>Definition at line <a class="el" href="dbus-bus_8c_source.html#l00815">815</a> of file <a class="el" href="dbus-bus_8c_source.html">dbus-bus.c</a>.</p>
<p>References <a class="el" href="group__DBusMacros.html#ga070d2ce7b6bb7e5c05602aa8c308d0c4">NULL</a>, and <a class="el" href="dbus-bus_8c_source.html#l00080">BusData::unique_name</a>.</p>
</div>
</div>
<a class="anchor" id="ga24d782c710f3d82caf1b1ed582dcf474"></a><!-- doxytag: member="dbus-bus.c::dbus_bus_get_unix_user" ref="ga24d782c710f3d82caf1b1ed582dcf474" args="(DBusConnection *connection, const char *name, DBusError *error)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">DBUS_EXPORT unsigned long <a class="el" href="group__DBusBus.html#ga24d782c710f3d82caf1b1ed582dcf474">dbus_bus_get_unix_user</a> </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structDBusConnection.html">DBusConnection</a> * </td>
<td class="paramname"><em>connection</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>name</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structDBusError.html">DBusError</a> * </td>
<td class="paramname"><em>error</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Asks the bus to return the UID the named connection authenticated as, if any. </p>
<p>Only works on UNIX; only works for connections on the same machine as the bus. If you are not on the same machine as the bus, then calling this is probably a bad idea, since the UID will mean little to your application.</p>
<p>For the system message bus you're guaranteed to be on the same machine since it only listens on a UNIX domain socket (at least, as shipped by default).</p>
<p>This function only works for connections that authenticated as a UNIX user, right now that includes all bus connections, but it's very possible to have connections with no associated UID. So check for errors and do something sensible if they happen.</p>
<p>This function will always return an error on Windows.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">connection</td><td>the connection </td></tr>
<tr><td class="paramname">name</td><td>a name owned by the connection </td></tr>
<tr><td class="paramname">error</td><td>location to store the error </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the unix user id, or ((unsigned)-1) if error is set </dd></dl>
<p>Definition at line <a class="el" href="dbus-bus_8c_source.html#l00865">865</a> of file <a class="el" href="dbus-bus_8c_source.html">dbus-bus.c</a>.</p>
<p>References <a class="el" href="dbus-connection_8c_source.html#l03535">dbus_connection_send_with_reply_and_block()</a>, <a class="el" href="dbus-shared_8h_source.html#l00088">DBUS_INTERFACE_DBUS</a>, <a class="el" href="dbus-message_8c_source.html#l01792">dbus_message_append_args()</a>, <a class="el" href="dbus-message_8c_source.html#l01980">dbus_message_get_args()</a>, <a class="el" href="dbus-message_8c_source.html#l01333">dbus_message_new_method_call()</a>, <a class="el" href="dbus-message_8c_source.html#l01690">dbus_message_unref()</a>, <a class="el" href="dbus-shared_8h_source.html#l00080">DBUS_PATH_DBUS</a>, <a class="el" href="dbus-shared_8h_source.html#l00076">DBUS_SERVICE_DBUS</a>, <a class="el" href="dbus-message_8c_source.html#l03796">dbus_set_error_from_message()</a>, <a class="el" href="dbus-protocol_8h_source.html#l00060">DBUS_TYPE_INVALID</a>, <a class="el" href="dbus-protocol_8h_source.html#l00102">DBUS_TYPE_STRING</a>, <a class="el" href="dbus-protocol_8h_source.html#l00086">DBUS_TYPE_UINT32</a>, <a class="el" href="dbus-sysdeps_8h_source.html#l00104">DBUS_UID_UNSET</a>, and <a class="el" href="group__DBusMacros.html#ga070d2ce7b6bb7e5c05602aa8c308d0c4">NULL</a>.</p>
</div>
</div>
<a class="anchor" id="ga5331b172dd8ed00eec130e894c5c2a0b"></a><!-- doxytag: member="dbus-bus.c::dbus_bus_name_has_owner" ref="ga5331b172dd8ed00eec130e894c5c2a0b" args="(DBusConnection *connection, const char *name, DBusError *error)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">DBUS_EXPORT <a class="el" href="group__DBusTypes.html#ga39c9cb0f3a2a8ad6f55cc4855d035349">dbus_bool_t</a> <a class="el" href="group__DBusBus.html#ga5331b172dd8ed00eec130e894c5c2a0b">dbus_bus_name_has_owner</a> </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structDBusConnection.html">DBusConnection</a> * </td>
<td class="paramname"><em>connection</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>name</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structDBusError.html">DBusError</a> * </td>
<td class="paramname"><em>error</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Asks the bus whether a certain name has an owner. </p>
<p>Using this can easily result in a race condition, since an owner can appear or disappear after you call this.</p>
<p>If you want to request a name, just request it; if you want to avoid replacing a current owner, don't specify <a class="el" href="group__DBusShared.html#ga0f16ed23be47eb22a37a227a6e39597b" title="Request to replace the current primary owner.">DBUS_NAME_FLAG_REPLACE_EXISTING</a> and you will get an error if there's already an owner.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">connection</td><td>the connection </td></tr>
<tr><td class="paramname">name</td><td>the name </td></tr>
<tr><td class="paramname">error</td><td>location to store any errors </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd><a class="el" href="group__DBusMacros.html#gaa8cecfc5c5c054d2875c03e77b7be15d" title="Expands to "1".">TRUE</a> if the name exists, <a class="el" href="group__DBusMacros.html#gaa93f0eb578d23995850d61f7d61c55c1" title="Expands to "0".">FALSE</a> if not or on error </dd></dl>
<p>Definition at line <a class="el" href="dbus-bus_8c_source.html#l01280">1280</a> of file <a class="el" href="dbus-bus_8c_source.html">dbus-bus.c</a>.</p>
<p>References <a class="el" href="dbus-connection_8c_source.html#l03535">dbus_connection_send_with_reply_and_block()</a>, <a class="el" href="dbus-shared_8h_source.html#l00088">DBUS_INTERFACE_DBUS</a>, <a class="el" href="dbus-message_8c_source.html#l01792">dbus_message_append_args()</a>, <a class="el" href="dbus-message_8c_source.html#l01980">dbus_message_get_args()</a>, <a class="el" href="dbus-message_8c_source.html#l01333">dbus_message_new_method_call()</a>, <a class="el" href="dbus-message_8c_source.html#l01690">dbus_message_unref()</a>, <a class="el" href="dbus-shared_8h_source.html#l00080">DBUS_PATH_DBUS</a>, <a class="el" href="dbus-shared_8h_source.html#l00076">DBUS_SERVICE_DBUS</a>, <a class="el" href="dbus-protocol_8h_source.html#l00070">DBUS_TYPE_BOOLEAN</a>, <a class="el" href="dbus-protocol_8h_source.html#l00060">DBUS_TYPE_INVALID</a>, <a class="el" href="dbus-protocol_8h_source.html#l00102">DBUS_TYPE_STRING</a>, <a class="el" href="group__DBusMacros.html#gaa93f0eb578d23995850d61f7d61c55c1">FALSE</a>, and <a class="el" href="group__DBusMacros.html#ga070d2ce7b6bb7e5c05602aa8c308d0c4">NULL</a>.</p>
</div>
</div>
<a class="anchor" id="ga0c21cf74d05c0bd8003846b56a588a4b"></a><!-- doxytag: member="dbus-bus.c::dbus_bus_register" ref="ga0c21cf74d05c0bd8003846b56a588a4b" args="(DBusConnection *connection, DBusError *error)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">DBUS_EXPORT <a class="el" href="group__DBusTypes.html#ga39c9cb0f3a2a8ad6f55cc4855d035349">dbus_bool_t</a> <a class="el" href="group__DBusBus.html#ga0c21cf74d05c0bd8003846b56a588a4b">dbus_bus_register</a> </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structDBusConnection.html">DBusConnection</a> * </td>
<td class="paramname"><em>connection</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structDBusError.html">DBusError</a> * </td>
<td class="paramname"><em>error</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Registers a connection with the bus. </p>
<p>This must be the first thing an application does when connecting to the message bus. If registration succeeds, the unique name will be set, and can be obtained using <a class="el" href="group__DBusBus.html#ga8c10339a1e62f6a2e5752d9c2270d37b" title="Gets the unique name of the connection as assigned by the message bus.">dbus_bus_get_unique_name()</a>.</p>
<p>This function will block until registration is complete.</p>
<p>If the connection has already registered with the bus (determined by checking whether <a class="el" href="group__DBusBus.html#ga8c10339a1e62f6a2e5752d9c2270d37b" title="Gets the unique name of the connection as assigned by the message bus.">dbus_bus_get_unique_name()</a> returns a non-<a class="el" href="group__DBusMacros.html#ga070d2ce7b6bb7e5c05602aa8c308d0c4" title="A null pointer, defined appropriately for C or C++.">NULL</a> value), then this function does nothing.</p>
<p>If you use <a class="el" href="group__DBusBus.html#ga77ba5250adb84620f16007e1b023cf26" title="Connects to a bus daemon and registers the client with it.">dbus_bus_get()</a> or <a class="el" href="group__DBusBus.html#ga9c62186f19cf3bd3c7c604bdcefb4e09" title="Connects to a bus daemon and registers the client with it as with dbus_bus_register().">dbus_bus_get_private()</a> this function will be called for you.</p>
<dl class="note"><dt><b>Note:</b></dt><dd>Just use <a class="el" href="group__DBusBus.html#ga77ba5250adb84620f16007e1b023cf26" title="Connects to a bus daemon and registers the client with it.">dbus_bus_get()</a> or <a class="el" href="group__DBusBus.html#ga9c62186f19cf3bd3c7c604bdcefb4e09" title="Connects to a bus daemon and registers the client with it as with dbus_bus_register().">dbus_bus_get_private()</a> instead of <a class="el" href="group__DBusBus.html#ga0c21cf74d05c0bd8003846b56a588a4b" title="Registers a connection with the bus.">dbus_bus_register()</a> and save yourself some pain. Using <a class="el" href="group__DBusBus.html#ga0c21cf74d05c0bd8003846b56a588a4b" title="Registers a connection with the bus.">dbus_bus_register()</a> manually is only useful if you have your own custom message bus not found in <a class="el" href="group__DBusShared.html#ga980320deb96476bee7555edcdebc3528" title="Well-known bus types.">DBusBusType</a>.</dd></dl>
<p>If you open a bus connection with <a class="el" href="group__DBusConnection.html#gacd32f819820266598c6b6847dfddaf9c" title="Gets a connection to a remote address.">dbus_connection_open()</a> or <a class="el" href="group__DBusConnection.html#ga434e3fc7ee420fd30e2f05e57ff26b1d" title="Opens a new, dedicated connection to a remote address.">dbus_connection_open_private()</a> you will have to <a class="el" href="group__DBusBus.html#ga0c21cf74d05c0bd8003846b56a588a4b" title="Registers a connection with the bus.">dbus_bus_register()</a> yourself, or make the appropriate registration method calls yourself. If you send the method calls yourself, call <a class="el" href="group__DBusBus.html#ga0366177076e88bf37771341f32b0551c" title="Sets the unique name of the connection, as assigned by the message bus.">dbus_bus_set_unique_name()</a> with the unique bus name you get from the bus.</p>
<p>For shared connections (created with <a class="el" href="group__DBusConnection.html#gacd32f819820266598c6b6847dfddaf9c" title="Gets a connection to a remote address.">dbus_connection_open()</a>) in a multithreaded application, you can't really make the registration calls yourself, because you don't know whether some other thread is also registering, and the bus will kick you off if you send two registration messages.</p>
<p>If you use <a class="el" href="group__DBusBus.html#ga0c21cf74d05c0bd8003846b56a588a4b" title="Registers a connection with the bus.">dbus_bus_register()</a> however, there is a lock that keeps both apps from registering at the same time.</p>
<p>The rule in a multithreaded app, then, is that <a class="el" href="group__DBusBus.html#ga0c21cf74d05c0bd8003846b56a588a4b" title="Registers a connection with the bus.">dbus_bus_register()</a> must be used to register, or you need to have your own locks that all threads in the app will respect.</p>
<p>In a single-threaded application you can register by hand instead of using <a class="el" href="group__DBusBus.html#ga0c21cf74d05c0bd8003846b56a588a4b" title="Registers a connection with the bus.">dbus_bus_register()</a>, as long as you check <a class="el" href="group__DBusBus.html#ga8c10339a1e62f6a2e5752d9c2270d37b" title="Gets the unique name of the connection as assigned by the message bus.">dbus_bus_get_unique_name()</a> to see if a unique name has already been stored by another thread before you send the registration messages.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">connection</td><td>the connection </td></tr>
<tr><td class="paramname">error</td><td>place to store errors </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd><a class="el" href="group__DBusMacros.html#gaa8cecfc5c5c054d2875c03e77b7be15d" title="Expands to "1".">TRUE</a> on success </dd></dl>
<p>Definition at line <a class="el" href="dbus-bus_8c_source.html#l00646">646</a> of file <a class="el" href="dbus-bus_8c_source.html">dbus-bus.c</a>.</p>
<p>References <a class="el" href="dbus-internals_8c_source.html#l00527">_dbus_strdup()</a>, <a class="el" href="dbus-connection_8c_source.html#l03535">dbus_connection_send_with_reply_and_block()</a>, <a class="el" href="dbus-shared_8h_source.html#l00088">DBUS_INTERFACE_DBUS</a>, <a class="el" href="dbus-message_8c_source.html#l01980">dbus_message_get_args()</a>, <a class="el" href="dbus-message_8c_source.html#l01333">dbus_message_new_method_call()</a>, <a class="el" href="dbus-message_8c_source.html#l01690">dbus_message_unref()</a>, <a class="el" href="dbus-shared_8h_source.html#l00080">DBUS_PATH_DBUS</a>, <a class="el" href="dbus-shared_8h_source.html#l00076">DBUS_SERVICE_DBUS</a>, <a class="el" href="dbus-message_8c_source.html#l03796">dbus_set_error_from_message()</a>, <a class="el" href="dbus-protocol_8h_source.html#l00060">DBUS_TYPE_INVALID</a>, <a class="el" href="dbus-protocol_8h_source.html#l00102">DBUS_TYPE_STRING</a>, <a class="el" href="group__DBusMacros.html#gaa93f0eb578d23995850d61f7d61c55c1">FALSE</a>, <a class="el" href="group__DBusMacros.html#ga070d2ce7b6bb7e5c05602aa8c308d0c4">NULL</a>, <a class="el" href="group__DBusMacros.html#gaa8cecfc5c5c054d2875c03e77b7be15d">TRUE</a>, and <a class="el" href="dbus-bus_8c_source.html#l00080">BusData::unique_name</a>.</p>
</div>
</div>
<a class="anchor" id="gaa4aa5ebe51cdbe8c0651609fc72e841a"></a><!-- doxytag: member="dbus-bus.c::dbus_bus_release_name" ref="gaa4aa5ebe51cdbe8c0651609fc72e841a" args="(DBusConnection *connection, const char *name, DBusError *error)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">DBUS_EXPORT int <a class="el" href="group__DBusBus.html#gaa4aa5ebe51cdbe8c0651609fc72e841a">dbus_bus_release_name</a> </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structDBusConnection.html">DBusConnection</a> * </td>
<td class="paramname"><em>connection</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>name</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structDBusError.html">DBusError</a> * </td>
<td class="paramname"><em>error</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Asks the bus to unassign the given name from this connection by invoking the ReleaseName method on the bus. </p>
<p>The "ReleaseName" method is canonically documented in the D-Bus specification.</p>
<p>Possible results are: <a class="el" href="group__DBusShared.html#gaf51666b3db57bfc94f0fef7604ba35e2" title="Service was released from the given name.">DBUS_RELEASE_NAME_REPLY_RELEASED</a> which means you owned the name or were in the queue to own it, and and now you don't own it and aren't in the queue. <a class="el" href="group__DBusShared.html#ga994df340fa233202857ea9358b935aac" title="Service is not an owner of the given name.">DBUS_RELEASE_NAME_REPLY_NOT_OWNER</a> which means someone else owns the name so you can't release it. <a class="el" href="group__DBusShared.html#ga2aebb664a3c1ea2c08740139f44c386a" title="The given name does not exist on the bus.">DBUS_RELEASE_NAME_REPLY_NON_EXISTENT</a> which means nobody owned the name.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">connection</td><td>the connection </td></tr>
<tr><td class="paramname">name</td><td>the name to remove </td></tr>
<tr><td class="paramname">error</td><td>location to store the error </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>a result code, -1 if error is set </dd></dl>
<p>Definition at line <a class="el" href="dbus-bus_8c_source.html#l01198">1198</a> of file <a class="el" href="dbus-bus_8c_source.html">dbus-bus.c</a>.</p>
<p>References <a class="el" href="dbus-connection_8c_source.html#l03535">dbus_connection_send_with_reply_and_block()</a>, <a class="el" href="dbus-shared_8h_source.html#l00088">DBUS_INTERFACE_DBUS</a>, <a class="el" href="dbus-message_8c_source.html#l01792">dbus_message_append_args()</a>, <a class="el" href="dbus-message_8c_source.html#l01980">dbus_message_get_args()</a>, <a class="el" href="dbus-message_8c_source.html#l01333">dbus_message_new_method_call()</a>, <a class="el" href="dbus-message_8c_source.html#l01690">dbus_message_unref()</a>, <a class="el" href="dbus-shared_8h_source.html#l00080">DBUS_PATH_DBUS</a>, <a class="el" href="dbus-shared_8h_source.html#l00076">DBUS_SERVICE_DBUS</a>, <a class="el" href="dbus-message_8c_source.html#l03796">dbus_set_error_from_message()</a>, <a class="el" href="dbus-protocol_8h_source.html#l00060">DBUS_TYPE_INVALID</a>, <a class="el" href="dbus-protocol_8h_source.html#l00102">DBUS_TYPE_STRING</a>, <a class="el" href="dbus-protocol_8h_source.html#l00086">DBUS_TYPE_UINT32</a>, and <a class="el" href="group__DBusMacros.html#ga070d2ce7b6bb7e5c05602aa8c308d0c4">NULL</a>.</p>
</div>
</div>
<a class="anchor" id="ga6e6b98e19fa4400de7ef99c27b866b99"></a><!-- doxytag: member="dbus-bus.c::dbus_bus_remove_match" ref="ga6e6b98e19fa4400de7ef99c27b866b99" args="(DBusConnection *connection, const char *rule, DBusError *error)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">DBUS_EXPORT void <a class="el" href="group__DBusBus.html#ga6e6b98e19fa4400de7ef99c27b866b99">dbus_bus_remove_match</a> </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structDBusConnection.html">DBusConnection</a> * </td>
<td class="paramname"><em>connection</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>rule</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structDBusError.html">DBusError</a> * </td>
<td class="paramname"><em>error</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Removes a previously-added match rule "by value" (the most recently-added identical rule gets removed). </p>
<p>The "rule" argument is the string form of a match rule.</p>
<p>The bus compares match rules semantically, not textually, so whitespace and ordering don't have to be identical to the rule you passed to <a class="el" href="group__DBusBus.html#ga4eb6401ba014da3dbe3dc4e2a8e5b3ef" title="Adds a match rule to match messages going through the message bus.">dbus_bus_add_match()</a>.</p>
<p>If you pass <a class="el" href="group__DBusMacros.html#ga070d2ce7b6bb7e5c05602aa8c308d0c4" title="A null pointer, defined appropriately for C or C++.">NULL</a> for the error, this function will not block; otherwise it will. See detailed explanation in docs for <a class="el" href="group__DBusBus.html#ga4eb6401ba014da3dbe3dc4e2a8e5b3ef" title="Adds a match rule to match messages going through the message bus.">dbus_bus_add_match()</a>.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">connection</td><td>connection to the message bus </td></tr>
<tr><td class="paramname">rule</td><td>textual form of match rule </td></tr>
<tr><td class="paramname">error</td><td>location to store any errors </td></tr>
</table>
</dd>
</dl>
<p>Definition at line <a class="el" href="dbus-bus_8c_source.html#l01576">1576</a> of file <a class="el" href="dbus-bus_8c_source.html">dbus-bus.c</a>.</p>
<p>References <a class="el" href="dbus-shared_8h_source.html#l00088">DBUS_INTERFACE_DBUS</a>, <a class="el" href="dbus-message_8c_source.html#l01792">dbus_message_append_args()</a>, <a class="el" href="dbus-message_8c_source.html#l01333">dbus_message_new_method_call()</a>, <a class="el" href="dbus-message_8c_source.html#l01690">dbus_message_unref()</a>, <a class="el" href="dbus-shared_8h_source.html#l00080">DBUS_PATH_DBUS</a>, <a class="el" href="dbus-shared_8h_source.html#l00076">DBUS_SERVICE_DBUS</a>, <a class="el" href="dbus-protocol_8h_source.html#l00060">DBUS_TYPE_INVALID</a>, <a class="el" href="dbus-protocol_8h_source.html#l00102">DBUS_TYPE_STRING</a>, and <a class="el" href="group__DBusMacros.html#ga070d2ce7b6bb7e5c05602aa8c308d0c4">NULL</a>.</p>
</div>
</div>
<a class="anchor" id="ga8a9024c78c4ea89b6271f19dbc7861b2"></a><!-- doxytag: member="dbus-bus.c::dbus_bus_request_name" ref="ga8a9024c78c4ea89b6271f19dbc7861b2" args="(DBusConnection *connection, const char *name, unsigned int flags, DBusError *error)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">DBUS_EXPORT int <a class="el" href="group__DBusBus.html#ga8a9024c78c4ea89b6271f19dbc7861b2">dbus_bus_request_name</a> </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structDBusConnection.html">DBusConnection</a> * </td>
<td class="paramname"><em>connection</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>name</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned int </td>
<td class="paramname"><em>flags</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structDBusError.html">DBusError</a> * </td>
<td class="paramname"><em>error</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Asks the bus to assign the given name to this connection by invoking the RequestName method on the bus. </p>
<p>This method is fully documented in the D-Bus specification. For quick reference, the flags and result codes are discussed here, but the specification is the canonical version of this information.</p>
<p>First you should know that for each bus name, the bus stores a queue of connections that would like to own it. Only one owns it at a time - called the primary owner. If the primary owner releases the name or disconnects, then the next owner in the queue atomically takes over.</p>
<p>So for example if you have an application org.freedesktop.TextEditor and multiple instances of it can be run, you can have all of them sitting in the queue. The first one to start up will receive messages sent to org.freedesktop.TextEditor, but if that one exits another will become the primary owner and receive messages.</p>
<p>The queue means you don't need to manually watch for the current owner to disappear and then request the name again.</p>
<p>When requesting a name, you can specify several flags.</p>
<p><a class="el" href="group__DBusShared.html#ga40b7a263caf8d6e39b39a8c7350a084f" title="Allow another service to become the primary owner if requested.">DBUS_NAME_FLAG_ALLOW_REPLACEMENT</a> and <a class="el" href="group__DBusShared.html#ga3c18c35e4c2dfbe9a0a5be47f4b4b6e9" title="If we can not become the primary owner do not place us in the queue.">DBUS_NAME_FLAG_DO_NOT_QUEUE</a> are properties stored by the bus for this connection with respect to each requested bus name. These properties are stored even if the connection is queued and does not become the primary owner. You can update these flags by calling RequestName again (even if you already own the name).</p>
<p><a class="el" href="group__DBusShared.html#ga40b7a263caf8d6e39b39a8c7350a084f" title="Allow another service to become the primary owner if requested.">DBUS_NAME_FLAG_ALLOW_REPLACEMENT</a> means that another requestor of the name can take it away from you by specifying <a class="el" href="group__DBusShared.html#ga0f16ed23be47eb22a37a227a6e39597b" title="Request to replace the current primary owner.">DBUS_NAME_FLAG_REPLACE_EXISTING</a>.</p>
<p><a class="el" href="group__DBusShared.html#ga3c18c35e4c2dfbe9a0a5be47f4b4b6e9" title="If we can not become the primary owner do not place us in the queue.">DBUS_NAME_FLAG_DO_NOT_QUEUE</a> means that if you aren't the primary owner, you don't want to be queued up - you only care about being the primary owner.</p>
<p>Unlike the other two flags, <a class="el" href="group__DBusShared.html#ga0f16ed23be47eb22a37a227a6e39597b" title="Request to replace the current primary owner.">DBUS_NAME_FLAG_REPLACE_EXISTING</a> is a property of the individual RequestName call, i.e. the bus does not persistently associate it with the connection-name pair. If a RequestName call includes the <a class="el" href="group__DBusShared.html#ga0f16ed23be47eb22a37a227a6e39597b" title="Request to replace the current primary owner.">DBUS_NAME_FLAG_REPLACE_EXISTING</a> flag, and the current primary owner has <a class="el" href="group__DBusShared.html#ga40b7a263caf8d6e39b39a8c7350a084f" title="Allow another service to become the primary owner if requested.">DBUS_NAME_FLAG_ALLOW_REPLACEMENT</a> set, then the current primary owner will be kicked off.</p>
<p>If no flags are given, an application will receive the requested name only if the name is currently unowned; and it will NOT give up the name if another application asks to take it over using <a class="el" href="group__DBusShared.html#ga0f16ed23be47eb22a37a227a6e39597b" title="Request to replace the current primary owner.">DBUS_NAME_FLAG_REPLACE_EXISTING</a>.</p>
<p>This function returns a result code. The possible result codes are as follows.</p>
<p><a class="el" href="group__DBusShared.html#ga37a9bc7c6eb11d212bf8d5e5ff3b50f9" title="Service has become the primary owner of the requested name.">DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER</a> means that the name had no existing owner, and the caller is now the primary owner; or that the name had an owner, and the caller specified <a class="el" href="group__DBusShared.html#ga0f16ed23be47eb22a37a227a6e39597b" title="Request to replace the current primary owner.">DBUS_NAME_FLAG_REPLACE_EXISTING</a>, and the current owner specified <a class="el" href="group__DBusShared.html#ga40b7a263caf8d6e39b39a8c7350a084f" title="Allow another service to become the primary owner if requested.">DBUS_NAME_FLAG_ALLOW_REPLACEMENT</a>.</p>
<p><a class="el" href="group__DBusShared.html#gaee62d7003ea4ed8c1957e9a072c7b16a" title="Service could not become the primary owner and has been placed in the queue.">DBUS_REQUEST_NAME_REPLY_IN_QUEUE</a> happens only if the caller does NOT specify <a class="el" href="group__DBusShared.html#ga3c18c35e4c2dfbe9a0a5be47f4b4b6e9" title="If we can not become the primary owner do not place us in the queue.">DBUS_NAME_FLAG_DO_NOT_QUEUE</a> and either the current owner did NOT specify <a class="el" href="group__DBusShared.html#ga40b7a263caf8d6e39b39a8c7350a084f" title="Allow another service to become the primary owner if requested.">DBUS_NAME_FLAG_ALLOW_REPLACEMENT</a> or the caller did NOT specify <a class="el" href="group__DBusShared.html#ga0f16ed23be47eb22a37a227a6e39597b" title="Request to replace the current primary owner.">DBUS_NAME_FLAG_REPLACE_EXISTING</a>. In this case the caller ends up in a queue to own the name after the current owner gives it up.</p>
<p><a class="el" href="group__DBusShared.html#gac5e749f4dfcc3adcdb714ece3c1be1c7" title="Service is already in the queue.">DBUS_REQUEST_NAME_REPLY_EXISTS</a> happens if the name has an owner already and the caller specifies <a class="el" href="group__DBusShared.html#ga3c18c35e4c2dfbe9a0a5be47f4b4b6e9" title="If we can not become the primary owner do not place us in the queue.">DBUS_NAME_FLAG_DO_NOT_QUEUE</a> and either the current owner has NOT specified <a class="el" href="group__DBusShared.html#ga40b7a263caf8d6e39b39a8c7350a084f" title="Allow another service to become the primary owner if requested.">DBUS_NAME_FLAG_ALLOW_REPLACEMENT</a> or the caller did NOT specify <a class="el" href="group__DBusShared.html#ga0f16ed23be47eb22a37a227a6e39597b" title="Request to replace the current primary owner.">DBUS_NAME_FLAG_REPLACE_EXISTING</a>.</p>
<p><a class="el" href="group__DBusShared.html#gaefd5513d0d448f6c106202ebde26f969" title="Service is already the primary owner.">DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER</a> happens if an application requests a name it already owns. (Re-requesting a name is useful if you want to change the <a class="el" href="group__DBusShared.html#ga40b7a263caf8d6e39b39a8c7350a084f" title="Allow another service to become the primary owner if requested.">DBUS_NAME_FLAG_ALLOW_REPLACEMENT</a> or <a class="el" href="group__DBusShared.html#ga3c18c35e4c2dfbe9a0a5be47f4b4b6e9" title="If we can not become the primary owner do not place us in the queue.">DBUS_NAME_FLAG_DO_NOT_QUEUE</a> settings.)</p>
<p>When a service represents an application, say "text editor," then it should specify <a class="el" href="group__DBusShared.html#ga40b7a263caf8d6e39b39a8c7350a084f" title="Allow another service to become the primary owner if requested.">DBUS_NAME_FLAG_ALLOW_REPLACEMENT</a> if it wants the last editor started to be the user's editor vs. the first one started. Then any editor that can be the user's editor should specify <a class="el" href="group__DBusShared.html#ga0f16ed23be47eb22a37a227a6e39597b" title="Request to replace the current primary owner.">DBUS_NAME_FLAG_REPLACE_EXISTING</a> to either take over (last-started-wins) or be queued up (first-started-wins) according to whether <a class="el" href="group__DBusShared.html#ga40b7a263caf8d6e39b39a8c7350a084f" title="Allow another service to become the primary owner if requested.">DBUS_NAME_FLAG_ALLOW_REPLACEMENT</a> was given.</p>
<p>Conventionally, single-instance applications often offer a command line option called --replace which means to replace the current instance. To implement this, always set <a class="el" href="group__DBusShared.html#ga40b7a263caf8d6e39b39a8c7350a084f" title="Allow another service to become the primary owner if requested.">DBUS_NAME_FLAG_ALLOW_REPLACEMENT</a> when you request your application's bus name. When you lose ownership of your bus name, you need to exit. Look for the signal "NameLost" from <a class="el" href="group__DBusShared.html#ga9e017e829e575bdc5c554fd4d07d7355" title="The bus name used to talk to the bus itself.">DBUS_SERVICE_DBUS</a> and <a class="el" href="group__DBusShared.html#gaa34514374bb61b8222a670a3d0b3fdc4" title="The interface exported by the object with DBUS_SERVICE_DBUS and DBUS_PATH_DBUS.">DBUS_INTERFACE_DBUS</a> (the signal's first argument is the bus name that was lost). If starting up without --replace, do not specify <a class="el" href="group__DBusShared.html#ga0f16ed23be47eb22a37a227a6e39597b" title="Request to replace the current primary owner.">DBUS_NAME_FLAG_REPLACE_EXISTING</a>, and exit if you fail to become the bus name owner. If --replace is given, ask to replace the old owner.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">connection</td><td>the connection </td></tr>
<tr><td class="paramname">name</td><td>the name to request </td></tr>
<tr><td class="paramname">flags</td><td>flags </td></tr>
<tr><td class="paramname">error</td><td>location to store the error </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>a result code, -1 if error is set </dd></dl>
<p>Definition at line <a class="el" href="dbus-bus_8c_source.html#l01112">1112</a> of file <a class="el" href="dbus-bus_8c_source.html">dbus-bus.c</a>.</p>
<p>References <a class="el" href="dbus-connection_8c_source.html#l03535">dbus_connection_send_with_reply_and_block()</a>, <a class="el" href="dbus-shared_8h_source.html#l00088">DBUS_INTERFACE_DBUS</a>, <a class="el" href="dbus-message_8c_source.html#l01792">dbus_message_append_args()</a>, <a class="el" href="dbus-message_8c_source.html#l01980">dbus_message_get_args()</a>, <a class="el" href="dbus-message_8c_source.html#l01333">dbus_message_new_method_call()</a>, <a class="el" href="dbus-message_8c_source.html#l01690">dbus_message_unref()</a>, <a class="el" href="dbus-shared_8h_source.html#l00080">DBUS_PATH_DBUS</a>, <a class="el" href="dbus-shared_8h_source.html#l00076">DBUS_SERVICE_DBUS</a>, <a class="el" href="dbus-message_8c_source.html#l03796">dbus_set_error_from_message()</a>, <a class="el" href="dbus-protocol_8h_source.html#l00060">DBUS_TYPE_INVALID</a>, <a class="el" href="dbus-protocol_8h_source.html#l00102">DBUS_TYPE_STRING</a>, <a class="el" href="dbus-protocol_8h_source.html#l00086">DBUS_TYPE_UINT32</a>, and <a class="el" href="group__DBusMacros.html#ga070d2ce7b6bb7e5c05602aa8c308d0c4">NULL</a>.</p>
</div>
</div>
<a class="anchor" id="ga0366177076e88bf37771341f32b0551c"></a><!-- doxytag: member="dbus-bus.c::dbus_bus_set_unique_name" ref="ga0366177076e88bf37771341f32b0551c" args="(DBusConnection *connection, const char *unique_name)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">DBUS_EXPORT <a class="el" href="group__DBusTypes.html#ga39c9cb0f3a2a8ad6f55cc4855d035349">dbus_bool_t</a> <a class="el" href="group__DBusBus.html#ga0366177076e88bf37771341f32b0551c">dbus_bus_set_unique_name</a> </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structDBusConnection.html">DBusConnection</a> * </td>
<td class="paramname"><em>connection</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>unique_name</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Sets the unique name of the connection, as assigned by the message bus. </p>
<p>Can only be used if you registered with the bus manually (i.e. if you did not call <a class="el" href="group__DBusBus.html#ga0c21cf74d05c0bd8003846b56a588a4b" title="Registers a connection with the bus.">dbus_bus_register()</a>). Can only be called once per connection. After the unique name is set, you can get it with <a class="el" href="group__DBusBus.html#ga8c10339a1e62f6a2e5752d9c2270d37b" title="Gets the unique name of the connection as assigned by the message bus.">dbus_bus_get_unique_name()</a>.</p>
<p>The only reason to use this function is to re-implement the equivalent of <a class="el" href="group__DBusBus.html#ga0c21cf74d05c0bd8003846b56a588a4b" title="Registers a connection with the bus.">dbus_bus_register()</a> yourself. One (probably unusual) reason to do that might be to do the bus registration call asynchronously instead of synchronously.</p>
<dl class="note"><dt><b>Note:</b></dt><dd>Just use <a class="el" href="group__DBusBus.html#ga77ba5250adb84620f16007e1b023cf26" title="Connects to a bus daemon and registers the client with it.">dbus_bus_get()</a> or <a class="el" href="group__DBusBus.html#ga9c62186f19cf3bd3c7c604bdcefb4e09" title="Connects to a bus daemon and registers the client with it as with dbus_bus_register().">dbus_bus_get_private()</a>, or worst case <a class="el" href="group__DBusBus.html#ga0c21cf74d05c0bd8003846b56a588a4b" title="Registers a connection with the bus.">dbus_bus_register()</a>, instead of messing with this function. There's really no point creating pain for yourself by doing things manually.</dd></dl>
<p>It's hard to use this function safely on shared connections (created by <a class="el" href="group__DBusConnection.html#gacd32f819820266598c6b6847dfddaf9c" title="Gets a connection to a remote address.">dbus_connection_open()</a>) in a multithreaded application, because only one registration attempt can be sent to the bus. If two threads are both sending the registration message, there is no mechanism in libdbus itself to avoid sending it twice.</p>
<p>Thus, you need a way to coordinate which thread sends the registration attempt; which also means you know which thread will call <a class="el" href="group__DBusBus.html#ga0366177076e88bf37771341f32b0551c" title="Sets the unique name of the connection, as assigned by the message bus.">dbus_bus_set_unique_name()</a>. If you don't know about all threads in the app (for example, if some libraries you're using might start libdbus-using threads), then you need to avoid using this function on shared connections.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">connection</td><td>the connection </td></tr>
<tr><td class="paramname">unique_name</td><td>the unique name </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd><a class="el" href="group__DBusMacros.html#gaa93f0eb578d23995850d61f7d61c55c1" title="Expands to "0".">FALSE</a> if not enough memory </dd></dl>
<p>Definition at line <a class="el" href="dbus-bus_8c_source.html#l00766">766</a> of file <a class="el" href="dbus-bus_8c_source.html">dbus-bus.c</a>.</p>
<p>References <a class="el" href="dbus-internals_8c_source.html#l00527">_dbus_strdup()</a>, <a class="el" href="group__DBusMacros.html#gaa93f0eb578d23995850d61f7d61c55c1">FALSE</a>, <a class="el" href="group__DBusMacros.html#ga070d2ce7b6bb7e5c05602aa8c308d0c4">NULL</a>, and <a class="el" href="dbus-bus_8c_source.html#l00080">BusData::unique_name</a>.</p>
</div>
</div>
<a class="anchor" id="ga81d303bf29d7c97ad4690ce35071b090"></a><!-- doxytag: member="dbus-bus.c::dbus_bus_start_service_by_name" ref="ga81d303bf29d7c97ad4690ce35071b090" args="(DBusConnection *connection, const char *name, dbus_uint32_t flags, dbus_uint32_t *result, DBusError *error)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">DBUS_EXPORT <a class="el" href="group__DBusTypes.html#ga39c9cb0f3a2a8ad6f55cc4855d035349">dbus_bool_t</a> <a class="el" href="group__DBusBus.html#ga81d303bf29d7c97ad4690ce35071b090">dbus_bus_start_service_by_name</a> </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structDBusConnection.html">DBusConnection</a> * </td>
<td class="paramname"><em>connection</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>name</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__DBusTypes.html#gaf513803b030613a669cc7ef199f90a8b">dbus_uint32_t</a> </td>
<td class="paramname"><em>flags</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__DBusTypes.html#gaf513803b030613a669cc7ef199f90a8b">dbus_uint32_t</a> * </td>
<td class="paramname"><em>result</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structDBusError.html">DBusError</a> * </td>
<td class="paramname"><em>error</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Starts a service that will request ownership of the given name. </p>
<p>The returned result will be one of be one of <a class="el" href="group__DBusShared.html#ga375114145e2eb43473fb778cc603f08b" title="Service was auto started.">DBUS_START_REPLY_SUCCESS</a> or <a class="el" href="group__DBusShared.html#gad6de6047e398631e590cdae679f044c5" title="Service was already running.">DBUS_START_REPLY_ALREADY_RUNNING</a> if successful. Pass <a class="el" href="group__DBusMacros.html#ga070d2ce7b6bb7e5c05602aa8c308d0c4" title="A null pointer, defined appropriately for C or C++.">NULL</a> if you don't care about the result.</p>
<p>The flags parameter is for future expansion, currently you should specify 0.</p>
<p>It's often easier to avoid explicitly starting services, and just send a method call to the service's bus name instead. Method calls start a service to handle them by default unless you call <a class="el" href="group__DBusMessage.html#ga1596d92a8d604f954b48c7410263d2f0" title="Sets a flag indicating that an owner for the destination name will be automatically started before th...">dbus_message_set_auto_start()</a> to disable this behavior.</p>
<dl class="params"><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">connection</td><td>the connection </td></tr>
<tr><td class="paramname">name</td><td>the name we want the new service to request </td></tr>
<tr><td class="paramname">flags</td><td>the flags (should always be 0 for now) </td></tr>
<tr><td class="paramname">result</td><td>a place to store the result or <a class="el" href="group__DBusMacros.html#ga070d2ce7b6bb7e5c05602aa8c308d0c4" title="A null pointer, defined appropriately for C or C++.">NULL</a> </td></tr>
<tr><td class="paramname">error</td><td>location to store any errors </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd><a class="el" href="group__DBusMacros.html#gaa8cecfc5c5c054d2875c03e77b7be15d" title="Expands to "1".">TRUE</a> if the activation succeeded, <a class="el" href="group__DBusMacros.html#gaa93f0eb578d23995850d61f7d61c55c1" title="Expands to "0".">FALSE</a> if not </dd></dl>
<p>Definition at line <a class="el" href="dbus-bus_8c_source.html#l01356">1356</a> of file <a class="el" href="dbus-bus_8c_source.html">dbus-bus.c</a>.</p>
<p>References <a class="el" href="dbus-connection_8c_source.html#l03535">dbus_connection_send_with_reply_and_block()</a>, <a class="el" href="dbus-shared_8h_source.html#l00088">DBUS_INTERFACE_DBUS</a>, <a class="el" href="dbus-message_8c_source.html#l01792">dbus_message_append_args()</a>, <a class="el" href="dbus-message_8c_source.html#l01980">dbus_message_get_args()</a>, <a class="el" href="dbus-message_8c_source.html#l01333">dbus_message_new_method_call()</a>, <a class="el" href="dbus-message_8c_source.html#l01690">dbus_message_unref()</a>, <a class="el" href="dbus-shared_8h_source.html#l00080">DBUS_PATH_DBUS</a>, <a class="el" href="dbus-shared_8h_source.html#l00076">DBUS_SERVICE_DBUS</a>, <a class="el" href="dbus-message_8c_source.html#l03796">dbus_set_error_from_message()</a>, <a class="el" href="dbus-protocol_8h_source.html#l00060">DBUS_TYPE_INVALID</a>, <a class="el" href="dbus-protocol_8h_source.html#l00102">DBUS_TYPE_STRING</a>, <a class="el" href="dbus-protocol_8h_source.html#l00086">DBUS_TYPE_UINT32</a>, <a class="el" href="group__DBusMacros.html#gaa93f0eb578d23995850d61f7d61c55c1">FALSE</a>, <a class="el" href="group__DBusMacros.html#ga070d2ce7b6bb7e5c05602aa8c308d0c4">NULL</a>, and <a class="el" href="group__DBusMacros.html#gaa8cecfc5c5c054d2875c03e77b7be15d">TRUE</a>.</p>
</div>
</div>
</div><!-- contents -->
<hr class="footer"/><address class="footer"><small>
Generated on Thu Mar 3 2016 17:50:32 for D-Bus by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.7.6.1
</small></address>
</body>
</html>