Message
Eldbus

## Topics

| Iterator
| Eina_Value to/from Message
| Message Helpers

## Functions

Eldbus_Message * | eldbus_message_ref (Eldbus_Message *msg)
| Increase message reference.
void | eldbus_message_unref (Eldbus_Message *msg)
| Decrease message reference.
const char * | eldbus_message_path_get (const Eldbus_Message *msg)
| Get the Eldbus message path.
const char * | eldbus_message_interface_get (const Eldbus_Message *msg)
| Get the Eldbus message interface.
const char * | eldbus_message_member_get (const Eldbus_Message *msg)
| Get the Eldbus message member.
const char * | eldbus_message_destination_get (const Eldbus_Message *msg)
| Get the Eldbus message destination.
const char * | eldbus_message_sender_get (const Eldbus_Message *msg)
| Get the Eldbus message sender.
const char * | eldbus_message_signature_get (const Eldbus_Message *msg)
| Get the Eldbus message signature.
Eldbus_Message * | eldbus_message_method_call_new (const char *dest, const char *path, const char *iface, const char *method)
| Create a new message to invoke a method on a remote object.
Eldbus_Message * | eldbus_message_signal_new (const char *path, const char *interface, const char *name)
| Create a new signal message.
Eldbus_Message * | eldbus_message_error_new (const Eldbus_Message *msg, const char *error_name, const char *error_msg)
| Create a new message that is an error reply to another message.
Eldbus_Message * | eldbus_message_method_return_new (const Eldbus_Message *msg)
| Create a message that is a reply to a method call.
Eina_Bool | eldbus_message_error_get (const Eldbus_Message *msg, const char **name, const char **text)
| Get the error text and name from a Eldbus_Message.
Eina_Bool | eldbus_message_arguments_get (const Eldbus_Message *msg, const char *signature,...)
| Get the arguments from an Eldbus_Message.
Eina_Bool | eldbus_message_arguments_vget (const Eldbus_Message *msg, const char *signature, va_list ap)
| Get the arguments from an Eldbus_Message using a va_list.
Eina_Bool | eldbus_message_arguments_append (Eldbus_Message *msg, const char *signature,...)
| Append arguments into an Eldbus_Message.
Eina_Bool | eldbus_message_arguments_vappend (Eldbus_Message *msg, const char *signature, va_list ap)
| Append arguments into an Eldbus_Message using a va_list.

## Detailed Description

## Function Documentation

## eldbus_message_ref()

Eldbus_Message * eldbus_message_ref | ( | Eldbus_Message * | msg | ) |

Increase message reference.

Parameters

  msg | The Eldbus_Message object.

Returns
  The previous Eldbus_Message with incremented refcount.

References DBG.

## eldbus_message_unref()

void eldbus_message_unref | ( | Eldbus_Message * | msg | ) |

Decrease message reference.

When refcount reaches zero the message and all its resources will be freed.

Parameters

  msg | The Eldbus_Message object.

References DBG, EINA_MAGIC_NONE, and EINA_MAGIC_SET.

Referenced by eldbus_message_method_call_new(), eldbus_proxy_property_set(), eldbus_proxy_property_value_set(), and eldbus_service_signal_emit().

## eldbus_message_path_get()

const char * eldbus_message_path_get | ( | const Eldbus_Message * | msg | ) |

Get the Eldbus message path.

Parameters

  msg | The Eldbus_Message object.

Returns
  A string containing the dbus message path.

## eldbus_message_interface_get()

const char * eldbus_message_interface_get | ( | const Eldbus_Message * | msg | ) |

Get the Eldbus message interface.

Parameters

  msg | The Eldbus_Message object.

Returns
  A string containing the dbus message interface.

## eldbus_message_member_get()

const char * eldbus_message_member_get | ( | const Eldbus_Message * | msg | ) |

Get the Eldbus message member.

Parameters

  msg | The Eldbus_Message object.

Returns
  A string containing the dbus message member.

## eldbus_message_destination_get()

const char * eldbus_message_destination_get | ( | const Eldbus_Message * | msg | ) |

Get the Eldbus message destination.

Parameters

  msg | The Eldbus_Message object.

Returns
  A string containing the dbus message destination.

## eldbus_message_sender_get()

const char * eldbus_message_sender_get | ( | const Eldbus_Message * | msg | ) |

Get the Eldbus message sender.

Parameters

  msg | The Eldbus_Message object.

Returns
  A string containing the dbus message sender.

## eldbus_message_signature_get()

const char * eldbus_message_signature_get | ( | const Eldbus_Message * | msg | ) |

Get the Eldbus message signature.

Parameters

  msg | The Eldbus_Message object.

Returns
  A string containing the dbus message signature.

## eldbus_message_method_call_new()

Eldbus_Message * eldbus_message_method_call_new | ( | const char * | dest,
|  | const char * | path,
|  | const char * | iface,
|  | const char * | method )

Create a new message to invoke a method on a remote object.

Parameters

  dest | bus name or unique id of the remote application
  path | object path
  iface | interface name
  method | name of the method to be called

Returns
  a new Eldbus_Message, free with eldbus_message_unref()

References EINA_SAFETY_ON_NULL_GOTO, EINA_SAFETY_ON_NULL_RETURN_VAL, EINA_TRUE, eldbus_message_unref(), and ERR.

Referenced by eldbus_object_method_call_new(), and eldbus_proxy_method_call_new().

## eldbus_message_signal_new()

Eldbus_Message * eldbus_message_signal_new | ( | const char * | path,
|  | const char * | interface,
|  | const char * | name )

Create a new signal message.

Parameters

  path | object path
  interface | interface name
  name | name of the signal to be broadcasted

Returns
  a new Eldbus_Message, free with eldbus_message_unref()

Since
  1.16

References EINA_SAFETY_ON_FALSE_RETURN_VAL, EINA_SAFETY_ON_NULL_RETURN_VAL, and EINA_TRUE.

Referenced by eldbus_service_signal_new().

## eldbus_message_error_new()

Eldbus_Message * eldbus_message_error_new | ( | const Eldbus_Message * | msg,
|  | const char * | error_name,
|  | const char * | error_msg )

Create a new message that is an error reply to another message.

Parameters

  msg | the message we're replying to
  error_name | the error name
  error_msg | the error message string

Returns
  a new Eldbus_Message, free with eldbus_message_unref()

References EINA_FALSE, and EINA_SAFETY_ON_NULL_RETURN_VAL.

Referenced by eldbus_pending_cancel().

## eldbus_message_method_return_new()

Eldbus_Message * eldbus_message_method_return_new | ( | const Eldbus_Message * | msg | ) |

Create a message that is a reply to a method call.

Parameters

  msg | the message we're replying to

Returns
  new Eldbus_Message, free with eldbus_message_unref()

References EINA_SAFETY_ON_NULL_RETURN_VAL, and EINA_TRUE.

## eldbus_message_error_get()

Eina_Bool eldbus_message_error_get | ( | const Eldbus_Message * | msg,
|  | const char ** | name,
|  | const char ** | text )

Get the error text and name from a Eldbus_Message.

If

Parameters

  msg | is an error message return EINA_TRUE and fill in the name and text of the error.
  msg | The message containing the error
  name | Variable in which to store the error name or `NULL` if it's not desired.
  text | Variable in which to store the error text or `NULL` if it's not desired.

Returns
  EINA_TRUE on success, else EINA_FALSE.

References EINA_FALSE, and EINA_TRUE.

## eldbus_message_arguments_get()

Eina_Bool eldbus_message_arguments_get | ( | const Eldbus_Message * | msg,
|  | const char * | signature,
|  |  | ... )

Get the arguments from an Eldbus_Message.

Get the arguments of an Eldbus_Message storing them in the locations pointed to by the pointer arguments that follow param signature. Each pointer argument must be of a type that is appropriate for the correspondent complete type in param signature. For complex types such as arrays, structs, dictionaries or variants, a pointer to Eldbus_Message_Iter* must be provided.

Parameters

  msg | The message to get the arguments from.
  signature | The signature of the arguments user is expecting to read from
  msg |
  ... | The pointers in which to store the message arguments

Returns
  EINA_TRUE if the arguments were read successfully and stored in the respective pointer arguments.

References EINA_FALSE, and EINA_SAFETY_ON_NULL_RETURN_VAL.

## eldbus_message_arguments_vget()

Eina_Bool eldbus_message_arguments_vget | ( | const Eldbus_Message * | msg,
|  | const char * | signature,
|  | va_list | ap )

Get the arguments from an Eldbus_Message using a va_list.

Parameters

  msg | The message to get the arguments from.
  signature | The signature user is expecting to read from param msg.
  ap | The va_list containing the pointer arguments.

See also
  eldbus_message_arguments_get()

Returns
  EINA_TRUE if the arguments were read successfully and stored in the respective pointer arguments.

References EINA_FALSE, and EINA_SAFETY_ON_NULL_RETURN_VAL.

## eldbus_message_arguments_append()

Eina_Bool eldbus_message_arguments_append | ( | Eldbus_Message * | msg,
|  | const char * | signature,
|  |  | ... )

Append arguments into an Eldbus_Message.

Append arguments into an Eldbus_Message according to the param signature provided. For each complete type in param signature, a value of the corresponding type must be provided.

This function supports only basic types. For complex types use eldbus_message_iter_* family of functions.

Parameters

  msg | The message in which arguments are being appended.
  signature | Signature of the arguments that are being appended.
  ... | Values of each argument to append in param msg.

Returns
  EINA_TRUE on success, EINA_FALSE otherwise.

References EINA_FALSE, and EINA_SAFETY_ON_NULL_RETURN_VAL.

## eldbus_message_arguments_vappend()

Eina_Bool eldbus_message_arguments_vappend | ( | Eldbus_Message * | msg,
|  | const char * | signature,
|  | va_list | ap )

Append arguments into an Eldbus_Message using a va_list.

Parameters

  msg | The message in which arguments are being appended.
  signature | Signature of the arguments that are being appended.
  ap | The va_list containing the arguments to append.

See also
  eldbus_message_arguments_append().

Returns
  EINA_TRUE on success, EINA_FALSE otherwise.

References EINA_FALSE, and EINA_SAFETY_ON_NULL_RETURN_VAL.

Referenced by eldbus_service_signal_emit().