Connection
Eldbus

## Macros

#define | ELDBUS_TIMEOUT_INFINITE ((int) 0x7fffffff)
| Infinite timeout definition.

## Typedefs

typedef void(* | Eldbus_Connection_Event_Cb) (void *data, Eldbus_Connection *conn, void *event_info)
| Callback called when we receive an event.

## Enumerations

enum | Eldbus_Connection_Type { ELDBUS_CONNECTION_TYPE_UNKNOWN = 0 , ELDBUS_CONNECTION_TYPE_SESSION , ELDBUS_CONNECTION_TYPE_SYSTEM , ELDBUS_CONNECTION_TYPE_STARTER , ELDBUS_CONNECTION_TYPE_ADDRESS , ELDBUS_CONNECTION_TYPE_LAST }
| Enum of several Eldbus connection types. More...
enum | Eldbus_Connection_Event_Type { ELDBUS_CONNECTION_EVENT_DEL , ELDBUS_CONNECTION_EVENT_DISCONNECTED , ELDBUS_CONNECTION_EVENT_LAST }
| Enum of several Eldbus connection events. More...

## Functions

Eldbus_Connection * | eldbus_connection_get (Eldbus_Connection_Type type)
| Establish a connection to bus and integrate it with the ecore main loop.
Eldbus_Connection * | eldbus_private_connection_get (Eldbus_Connection_Type type)
| Always create and establish a new connection to bus and integrate it with the ecore main loop.
Eldbus_Connection * | eldbus_address_connection_get (const char *address)
| Establish a connection to bus and integrate it with the ecore main loop.
Eldbus_Connection * | eldbus_private_address_connection_get (const char *address)
| Always create and establish a new connection to bus and integrate it with the ecore main loop.
Eldbus_Connection * | eldbus_connection_ref (Eldbus_Connection *conn)
| Increment connection reference count.
void | eldbus_connection_unref (Eldbus_Connection *conn)
| Decrement connection reference count.
void | eldbus_connection_free_cb_add (Eldbus_Connection *conn, Eldbus_Free_Cb cb, const void *data)
| Add a callback function to be called when connection is freed.
void | eldbus_connection_free_cb_del (Eldbus_Connection *conn, Eldbus_Free_Cb cb, const void *data)
| Remove callback registered in eldbus_connection_free_cb_add().
void | eldbus_connection_data_set (Eldbus_Connection *conn, const char *key, const void *data)
| Set an attached data pointer to an object with a given string key.
void * | eldbus_connection_data_get (const Eldbus_Connection *conn, const char *key)
| Get data stored in connection.
void * | eldbus_connection_data_del (Eldbus_Connection *conn, const char *key)
| Del data stored in connection.
void | eldbus_connection_event_callback_add (Eldbus_Connection *conn, Eldbus_Connection_Event_Type type, Eldbus_Connection_Event_Cb cb, const void *cb_data)
| Add a callback function to be called when an event occurs of the type passed.
void | eldbus_connection_event_callback_del (Eldbus_Connection *conn, Eldbus_Connection_Event_Type type, Eldbus_Connection_Event_Cb cb, const void *cb_data)
| Remove callback registered in eldbus_connection_event_callback_add().
Eldbus_Pending * | eldbus_connection_send (Eldbus_Connection *conn, Eldbus_Message *msg, Eldbus_Message_Cb cb, const void *cb_data, double timeout)
| Send a message.
const char * | eldbus_connection_unique_name_get (Eldbus_Connection *conn)
| Gets unique name assigned by the message bus.

## Detailed Description

## Enumeration Type Documentation

## Eldbus_Connection_Type

enum Eldbus_Connection_Type

Enum of several Eldbus connection types.

Enumerator
ELDBUS_CONNECTION_TYPE_UNKNOWN | sentinel, not a real type
ELDBUS_CONNECTION_TYPE_LAST | sentinel, not a real type

## Eldbus_Connection_Event_Type

enum Eldbus_Connection_Event_Type

Enum of several Eldbus connection events.

Enumerator
ELDBUS_CONNECTION_EVENT_LAST | sentinel, not a real event type

## Function Documentation

## eldbus_connection_get()

Eldbus_Connection * eldbus_connection_get | ( | Eldbus_Connection_Type | type | ) |

Establish a connection to bus and integrate it with the ecore main loop.

If a connection of given type was already created before, its reference counter is incremented and the connection is returned.

Parameters

  type | type of connection e.g ELDBUS_CONNECTION_TYPE_SESSION, ELDBUS_CONNECTION_TYPE_SYSTEM or ELDBUS_CONNECTION_TYPE_STARTER

Returns
  connection with bus

Examples
  banshee.c, client.c, complex-types-client-eina-value.c, complex-types-server.c, complex-types.c, connman-list-services.c, ofono-dial.c, server.c, and simple-signal-emit.c.

References DBG, EINA_SAFETY_ON_NULL_RETURN_VAL, EINA_TRUE, eldbus_connection_ref(), and ERR.

Referenced by efl_net_connman_init(), elm_color_class_editor_add(), and ethumb_client_connect().

## eldbus_private_connection_get()

Eldbus_Connection * eldbus_private_connection_get | ( | Eldbus_Connection_Type | type | ) |

Always create and establish a new connection to bus and integrate it with the ecore main loop.

Differently from eldbus_connection_get(), this function guarantees to create a new connection to the D-Bus daemon and the connection is not shared by any means.

Parameters

  type | type of connection e.g ELDBUS_CONNECTION_TYPE_SESSION, ELDBUS_CONNECTION_TYPE_SYSTEM or ELDBUS_CONNECTION_TYPE_STARTER

Returns
  connection with bus

References DBG, and EINA_FALSE.

## eldbus_address_connection_get()

Eldbus_Connection * eldbus_address_connection_get | ( | const char * | address | ) |

Establish a connection to bus and integrate it with the ecore main loop.

If a connection of given type was already created before, its reference counter is incremented and the connection is returned.

Parameters

  address | the address which will be passed to dbus_connection_open()

Returns
  connection with bus

References DBG, eina_hash_add(), eina_hash_find(), eina_hash_string_small_new(), EINA_SAFETY_ON_NULL_RETURN_VAL, EINA_TRUE, and eldbus_connection_ref().

## eldbus_private_address_connection_get()

Eldbus_Connection * eldbus_private_address_connection_get | ( | const char * | address | ) |

Always create and establish a new connection to bus and integrate it with the ecore main loop.

Differently from eldbus_connection_get(), this function guarantees to create a new connection to the D-Bus daemon and the connection is not shared by any means.

Parameters

  address | the address which will be passed to dbus_connection_open_private()

Returns
  connection with bus

References DBG, and EINA_FALSE.

## eldbus_connection_ref()

Eldbus_Connection * eldbus_connection_ref | ( | Eldbus_Connection * | conn | ) |

Increment connection reference count.

Parameters

  conn | The given Eldbus_Connection object to reference.

Returns
  The Eldbus_Connection object given as parameter.

References DBG.

Referenced by eldbus_address_connection_get(), and eldbus_connection_get().

## eldbus_connection_unref()

void eldbus_connection_unref | ( | Eldbus_Connection * | conn | ) |

Decrement connection reference count.

If reference count reaches 0, the connection to bus will be dropped and all its children will be invalidated.

Parameters

  conn | The given Eldbus_Connection object to unreference.

Examples
  banshee.c, client.c, complex-types-client-eina-value.c, complex-types-server.c, complex-types.c, connman-list-services.c, ofono-dial.c, server.c, and simple-signal-emit.c.

References DBG.

Referenced by efl_net_connman_init(), and efl_net_connman_shutdown().

## eldbus_connection_free_cb_add()

void eldbus_connection_free_cb_add | ( | Eldbus_Connection * | conn,
|  | Eldbus_Free_Cb | cb,
|  | const void * | data )

Add a callback function to be called when connection is freed.

Parameters

  conn | The connection object to add the callback to.
  cb | The callback to be called when the connection is free.
  data | The data passed to the callback.

References EINA_SAFETY_ON_NULL_RETURN.

Referenced by eldbus_object_get(), and eldbus_signal_handler_add().

## eldbus_connection_free_cb_del()

void eldbus_connection_free_cb_del | ( | Eldbus_Connection * | conn,
|  | Eldbus_Free_Cb | cb,
|  | const void * | data )

Remove callback registered in eldbus_connection_free_cb_add().

Parameters

  conn | The connection object to delete the callback from.
  cb | The callback that was called when the connection was free.
  data | The data that was passed to the callback.

References EINA_SAFETY_ON_NULL_RETURN.

Referenced by eldbus_service_object_unregister().

## eldbus_connection_data_set()

void eldbus_connection_data_set | ( | Eldbus_Connection * | conn,
|  | const char * | key,
|  | const void * | data )

Set an attached data pointer to an object with a given string key.

Parameters

  conn | The connection object to store data to
  key | to identify data
  data | data that will be stored

References EINA_SAFETY_ON_NULL_RETURN.

## eldbus_connection_data_get()

void * eldbus_connection_data_get | ( | const Eldbus_Connection * | conn,
|  | const char * | key )

Get data stored in connection.

Parameters

  conn | connection where data is stored
  key | key that identifies data

Returns
  pointer to data if found otherwise NULL

References EINA_SAFETY_ON_NULL_RETURN_VAL.

## eldbus_connection_data_del()

void * eldbus_connection_data_del | ( | Eldbus_Connection * | conn,
|  | const char * | key )

Del data stored in connection.

Parameters

  conn | connection where data is stored
  key | that identifies data

Returns
  pointer to data if found otherwise NULL

References EINA_SAFETY_ON_NULL_RETURN_VAL.

## eldbus_connection_event_callback_add()

void eldbus_connection_event_callback_add | ( | Eldbus_Connection * | conn,
|  | Eldbus_Connection_Event_Type | type,
|  | Eldbus_Connection_Event_Cb | cb,
|  | const void * | cb_data )

Add a callback function to be called when an event occurs of the type passed.

Parameters

  conn | The connection object to add the callback to.
  type | The type of event that will trigger the callback.
  cb | The callback to be called when the event is triggered.
  cb_data | The data passed to the callback.

References eina_inlist_append(), EINA_INLIST_GET, EINA_SAFETY_ON_NULL_RETURN, EINA_SAFETY_ON_TRUE_RETURN, and ELDBUS_CONNECTION_EVENT_LAST.

## eldbus_connection_event_callback_del()

void eldbus_connection_event_callback_del | ( | Eldbus_Connection * | conn,
|  | Eldbus_Connection_Event_Type | type,
|  | Eldbus_Connection_Event_Cb | cb,
|  | const void * | cb_data )

Remove callback registered in eldbus_connection_event_callback_add().

Parameters

  conn | The connection object to delete the callback from.
  type | The type of event that was triggered the callback.
  cb | The callback that was called when the event was triggered.
  cb_data | The data that was passed to the callback.

References EINA_INLIST_FOREACH, eina_list_append(), EINA_SAFETY_ON_NULL_RETURN, EINA_SAFETY_ON_TRUE_RETURN, EINA_TRUE, and ELDBUS_CONNECTION_EVENT_LAST.

## eldbus_connection_send()

Eldbus_Pending * eldbus_connection_send | ( | Eldbus_Connection * | conn,
|  | Eldbus_Message * | msg,
|  | Eldbus_Message_Cb | cb,
|  | const void * | cb_data,
|  | double | timeout )

Send a message.

Parameters

  conn | the connection where the message will be sent
  msg | message that will be sent
  cb | if msg is a method call a callback should be passed to be executed when a response arrives
  cb_data | data passed to callback
  timeout | timeout in milliseconds, -1 to use default internal value or ELDBUS_TIMEOUT_INFINITE for no timeout

Returns
  A Eldbus_Pending struct.

Examples
  server.c.

References EINA_SAFETY_ON_NULL_RETURN_VAL, and eldbus_pending_data_set().

## eldbus_connection_unique_name_get()

const char * eldbus_connection_unique_name_get | ( | Eldbus_Connection * | conn | ) |

Gets unique name assigned by the message bus.

Parameters

  conn | connection object to get unique name from.

Returns
  pointer to unique name string or NULL or error. Returned value remains valid until connection is free.

Referenced by efl_net_connman_init().