Class | DBus::Binding::DBusMessage |
In: |
ruby-dbus.c
lib/dbus/binding.rb |
Parent: | Object |
Represents a message sent over or received from another application over the bus.
A message has a type (DBusMessage#get_type) field indicating the nature of the message, and this can be used to decide which additional fields will contain useful data.
In addition, a message can have application-specific values added to it, these are called values or arguments. The order and type of the appended values define the message type signature (see DBusMessage#get_signature).
Creates a new DBusMessage of the specified type, which may be one of the DBus MESSAGE_TYPE constants.
/* * call-seq: * new(type) => self * * Creates a new DBusMessage of the specified type, which may be one * of the DBus MESSAGE_TYPE constants. */ static VALUE cDBusMessage_new(VALUE klass, VALUE type) { DBusMessage *message; int message_type; message_type = NUM2INT(type); switch (message_type) { case DBUS_MESSAGE_TYPE_INVALID: case DBUS_MESSAGE_TYPE_METHOD_CALL: case DBUS_MESSAGE_TYPE_METHOD_RETURN: case DBUS_MESSAGE_TYPE_ERROR: case DBUS_MESSAGE_TYPE_SIGNAL: /* fall-through */ break; default: rb_raise(eDBusError, "unsupported DBusMessageType %d", message_type); } message = NULL; message = dbus_message_new(message_type); RDBUS_RAISE_IF(message == NULL, "failed to create DBusMessage"); return MSG_NEW_TAKE_OWNERSHIP(message); }
Creates a new DBusMessage of type MESSAGE_TYPE_ERROR.
Messages of this type are sent when a request fails for some reason. The error name has to be in a valid D-BUS error name format, meaning it has to contain at least one period.
/* * call-seq: * new_error(request_message, error_name, error_message) * * Creates a new DBusMessage of type MESSAGE_TYPE_ERROR. * * Messages of this type are sent when a request fails for some reason. * The error name has to be in a valid D-BUS error name format, meaning * it has to contain at least one period. */ static VALUE cDBusMessage_new_error(VALUE klass, VALUE reply_to, VALUE error_name, VALUE error_message) { DBusMessage *message; message = NULL; message = dbus_message_new_error( MSG_GET(reply_to), StringValuePtr(error_name), StringValuePtr(error_message) ); RDBUS_RAISE_IF(!message, "failed to create DBusMessage"); return MSG_NEW_TAKE_OWNERSHIP(message); }
Creates a new DBusMessage representing a method call request on a remote object.
/* * call-seq: * new_method_call(service, path, interface, method_name) => self * * Creates a new DBusMessage representing a method call request on a remote * object. * * - +service+ must contain the service to send the message to * - +path+ must contain object path the message should be sent to * - +interface+ must indicate the interface the method will be * invoked on * - +method_name+ must contain the name of a method defined in the given * interface */ static VALUE cDBusMessage_new_method_call(VALUE klass, VALUE service, VALUE path, VALUE interface, VALUE method) { DBusMessage *message; message = NULL; message = dbus_message_new_method_call( StringValuePtr(service), StringValuePtr(path), StringValuePtr(interface), StringValuePtr(method) ); RDBUS_RAISE_IF(message == NULL, "failed to create DBusMessage"); return MSG_NEW_TAKE_OWNERSHIP(message); }
Creates a new DBusMessage representing a reply to a method call.
The original method invocation request message must be provided in invocation_message.
/* * call-seq: * new_method_return(invocation_message) => self * * Creates a new DBusMessage representing a reply to a method call. * * The original method invocation request message must be provided in * +invocation_message+. */ static VALUE cDBusMessage_new_method_return(VALUE klass, VALUE method_call_msg) { DBusMessage *message; message = NULL; message = dbus_message_new_method_return(MSG_GET(method_call_msg)); RDBUS_RAISE_IF(!message, "failed to create DBusMessage"); return MSG_NEW_TAKE_OWNERSHIP(message); }
Creates a new DBusMessage representing a signal emission.
The given path must be the path to the object emitting the signal, interface the interface the signal is being emitted from, and signal_name the name of the signal.
The signal name can subsequently be retrieved from the member field of the message.
/* * call-seq: * new_signal(path, interface, signal_name) => self * * Creates a new DBusMessage representing a signal emission. * * The given +path+ must be the path to the object emitting the signal, * +interface+ the interface the signal is being emitted from, and +signal_name+ * the name of the signal. * * The signal name can subsequently be retrieved from the +member+ field * of the message. */ static VALUE cDBusMessage_new_signal(VALUE klass, VALUE path, VALUE interface, VALUE name) { DBusMessage *message; message = NULL; message = dbus_message_new_signal( StringValuePtr(path), StringValuePtr(interface), StringValuePtr(name) ); RDBUS_RAISE_IF(!message, "failed to create DBusMessage"); return MSG_NEW_TAKE_OWNERSHIP(message); }
Appends the given value to the message. If you want to append more than one value, use DBusMessage#append instead, it will be more efficient.
# File lib/dbus/binding.rb, line 76 76: def <<(value) 77: iter = get_append_iter 78: iter.append(value) 79: nil 80: end
Returns the message argument value at the given offset
# File lib/dbus/binding.rb, line 63 63: def [](offset) 64: entries[offset] 65: end
Appends each item in the given Array to the message
# File lib/dbus/binding.rb, line 68 68: def append(ary) 69: iter = get_append_iter 70: ary.each{|value| iter.append(value)} 71: nil 72: end
Yields each message argument value that was appended to the message to the given block, in sequence
# File lib/dbus/binding.rb, line 45 45: def each 46: raise DBusError, "block expected" unless block_given? 47: iter = get_iter 48: begin 49: value = iter.value 50: rescue 51: return nil 52: end 53: yield value 54: have_value = iter.next 55: while have_value 56: yield iter.value 57: have_value = iter.next 58: end 59: nil 60: end
Returns a DBusMessageIter iterator instance for appending values to this message. The position of the iterator is at the end of any existing values.
/* * call-seq: * get_append_iter => message append iterator * * Returns a DBusMessageIter iterator instance for appending values to * this message. The position of the iterator is at the end of any existing * values. */ static VALUE cDBusMessage_get_append_iter(VALUE self) { return ITER_NEW(MSG_GET(self), TRUE); }
Returns true if the message will cause the addressed service to be auto-activated.
/* * call-seq: * get_auto_activation => true|false * * Returns +true+ if the message will cause the addressed service * to be auto-activated. */ static VALUE cDBusMessage_get_auto_activation(VALUE self) { if (!dbus_message_get_auto_activation(MSG_GET(self))) return Qfalse; return Qtrue; }
Gets the destination service of this message.
/* * call-seq: * get_destination => service * * Gets the destination service of this message. */ static VALUE cDBusMessage_get_destination(VALUE self) { MESSAGE_STR_GETTER_BODY(destination); }
Gets the error name (for an error message).
/* * call-seq: * get_error_name => name * * Gets the error name (for an error message). */ static VALUE cDBusMessage_get_error_name(VALUE self) { MESSAGE_STR_GETTER_BODY(error_name); }
Gets the interface this message is being sent to.
/* * call-seq: * get_path => objectpath * * Gets the interface this message is being sent to. */ static VALUE cDBusMessage_get_interface(VALUE self) { MESSAGE_STR_GETTER_BODY(interface); }
Returns a DBusMessageIter iterator instance for this message. The iterator can be used to iterate over the values (arguments) appended to the message.
To append values to the message, use DBusMessage#get_append_iter instead, as its position will already be at the end, and by using it you will avoid D-BUS error messages.
/* * call-seq: * get_iter => message iterator * * Returns a DBusMessageIter iterator instance for this message. The * iterator can be used to iterate over the values (arguments) appended * to the message. * * To append values to the message, use DBusMessage#get_append_iter instead, * as its position will already be at the end, and by using it you will avoid * D-BUS error messages. */ static VALUE cDBusMessage_get_iter(VALUE self) { return ITER_NEW(MSG_GET(self), FALSE); }
Gets the interface member being invoked (for a method call), or emitted (for a signal).
/* * call-seq: * get_member => membername * * Gets the interface member being invoked (for a method call), or * emitted (for a signal). */ static VALUE cDBusMessage_get_member(VALUE self) { MESSAGE_STR_GETTER_BODY(member); }
Returns true if the message sender is not expecting a reply message.
/* * call-seq: * get_no_reply => true|false * * Returns +true+ if the message sender is not expecting a reply message. */ static VALUE cDBusMessage_get_no_reply(VALUE self) { if (!dbus_message_get_no_reply(MSG_GET(self))) return Qfalse; return Qtrue; }
Gets the object path this message is being sent to (for a method call), or being emitted from (for a signal).
/* * call-seq: * get_path => objectpath * * Gets the object path this message is being sent to (for a method call), * or being emitted from (for a signal). */ static VALUE cDBusMessage_get_path(VALUE self) { MESSAGE_STR_GETTER_BODY(path); }
Returns an array containing the path segments of the message path
# File lib/dbus/binding.rb, line 83 83: def get_path_decomposed 84: get_path.split("/") 85: end
Returns the serial number (see DbusMessage#get_serial) of the message that this message is a reply to.
/* * call-seq: * get_reply_serial => serial * * Returns the serial number (see DbusMessage#get_serial) of the message * that this message is a reply to. */ static VALUE cDBusMessage_get_reply_serial(VALUE self) { return INT2NUM(dbus_message_get_reply_serial(MSG_GET(self))); }
Gets the sending service of this message.
/* * call-seq: * get_sender => service * * Gets the sending service of this message. */ static VALUE cDBusMessage_get_sender(VALUE self) { MESSAGE_STR_GETTER_BODY(sender); }
Returns the client serial number of the message. This can’t be set.
/* * call-seq: * get_serial => serial * * Returns the client serial number of the message. This can't be set. */ static VALUE cDBusMessage_get_serial(VALUE self) { return INT2NUM(dbus_message_get_serial(MSG_GET(self))); }
Gets the type signature.
A type signature is the type of the message argument values in the message payload. The signature is a string consisting of TYPE_xxx type codes:
/* * call-seq: * get_signature => service * * Gets the type signature. * * A type signature is the type of the message argument values in the message * payload. The signature is a string consisting of TYPE_xxx type codes: */ static VALUE cDBusMessage_get_signature(VALUE self) { MESSAGE_STR_GETTER_BODY(signature); }
Returns an integer representing the message type. Its value will be one of the MESSAGE_TYPE constants.
/* * call-seq: * get_type => type * * Returns an integer representing the message type. Its value will * be one of the MESSAGE_TYPE constants. */ static VALUE cDBusMessage_get_type(VALUE self) { return INT2FIX(dbus_message_get_type(MSG_GET(self))); }
Returns true if the message has a destination service with the given service name.
/* * call-seq: * has_destination(service) => true | false * * Returns +true+ if the message has a destination service with the given * service name. */ static VALUE cDBusMessage_has_destination(VALUE self, VALUE service) { if (!dbus_message_has_destination(MSG_GET(self), StringValuePtr(service))) return Qfalse; return Qtrue; }
Returns true if the message has the given service name as its sender.
/* * call-seq: * has_sender(service) => true | false * * Returns +true+ if the message has the given service name as its sender. */ static VALUE cDBusMessage_has_sender(VALUE self, VALUE service) { if (!dbus_message_has_sender(MSG_GET(self), StringValuePtr(service))) return Qfalse; return Qtrue; }
Returns true if the message has the given type signature. See DBusMessage#get_signature for more details on type signatures.
/* * call-seq: * has_signature(signature) => true | false * * Returns +true+ if the message has the given type signature. * See DBusMessage#get_signature for more details on type signatures. */ static VALUE cDBusMessage_has_signature(VALUE self, VALUE signature) { if (!dbus_message_has_signature(MSG_GET(self), StringValuePtr(signature))) return Qfalse; return Qtrue; }
Returns true if the message is an error message with the given error name field.
/* * call-seq: * is_error(error_name) * * Returns +true+ if the message is an error message with the given error * name field. */ static VALUE cDBusMessage_is_error(VALUE self, VALUE error) { if (!dbus_message_is_error(MSG_GET(self), StringValuePtr(error))) return Qfalse; return Qtrue; }
Returns true if the message is a method call message with the given method name and interface fields.
/* * call-seq: * is_method_call(interface, method_name) => true | false * * Returns +true+ if the message is a method call message with the given * method name and interface fields. */ static VALUE cDBusMessage_is_method_call(VALUE self, VALUE interface, VALUE method) { if (!dbus_message_is_method_call(MSG_GET(self), StringValuePtr(interface), StringValuePtr(method))) return Qfalse; return Qtrue; }
Returns true if the message is a signal message with the given interface and signal name fields.
/* * call-seq: * is_signal(interface, signal_name) => true | false * * Returns +true+ if the message is a signal message with the given interface * and signal name fields. */ static VALUE cDBusMessage_is_signal(VALUE self, VALUE interface, VALUE signal_name) { if (!dbus_message_is_signal(MSG_GET(self), StringValuePtr(interface), StringValuePtr(signal_name))) return Qfalse; return Qtrue; }
Indicates that the addressed service will be auto-activated before the message is delivered. If the service fails to activate, an activation error reply message will be received.
/* * call-seq: * set_auto_activation(true|false) => nil * * Indicates that the addressed service will be auto-activated before * the message is delivered. If the service fails to activate, an * activation error reply message will be received. */ static VALUE cDBusMessage_set_auto_activation(VALUE self, VALUE value) { dbus_bool_t val; if (TYPE(value) == T_FALSE || TYPE(value) == T_NIL) val = FALSE; else val = TRUE; dbus_message_set_auto_activation(MSG_GET(self), val); return Qnil; }
Sets the message’s destination service.
Returns false if not enough memory.
/* * call-seq: * set_destination(service) => true|false * * Sets the message's destination service. * * Returns +false+ if not enough memory. */ static VALUE cDBusMessage_set_destination(VALUE self, VALUE value) { MESSAGE_STR_SETTER_BODY(destination); }
Sets the name of the error (for an error message).
Returns false if not enough memory.
/* * call-seq: * set_error_name(name) => true|false * * Sets the name of the error (for an error message). * * Returns +false+ if not enough memory. */ static VALUE cDBusMessage_set_error_name(VALUE self, VALUE value) { MESSAGE_STR_SETTER_BODY(error_name); }
Sets the interface this message is being sent to (for a method call), or the interface a signal is being emitted from (for a signal).
Returns false if not enough memory.
/* * call-seq: * set_interface(interface) => true|false * * Sets the interface this message is being sent to (for a method call), or * the interface a signal is being emitted from (for a signal). * * Returns +false+ if not enough memory. */ static VALUE cDBusMessage_set_interface(VALUE self, VALUE value) { MESSAGE_STR_SETTER_BODY(interface); }
Sets the interface member being invoked (for a method call), or emitted (for a signal).
Returns false if not enough memory.
/* * call-seq: * set_member(member) => true|false * * Sets the interface member being invoked (for a method call), or emitted * (for a signal). * * Returns +false+ if not enough memory. */ static VALUE cDBusMessage_set_member(VALUE self, VALUE value) { MESSAGE_STR_SETTER_BODY(member); }
Indicates whether or not the message wants a reply. If set, there is no way to know whether a message arrived successfully at the destination.
/* * call-seq: * set_no_reply(true|false) => nil * * Indicates whether or not the message wants a reply. If set, there is no * way to know whether a message arrived successfully at the destination. */ static VALUE cDBusMessage_set_no_reply(VALUE self, VALUE value) { dbus_bool_t val; if (TYPE(value) == T_FALSE || TYPE(value) == T_NIL) val = FALSE; else val = TRUE; dbus_message_set_no_reply(MSG_GET(self), val); return Qnil; }
Sets the object path this message is being sent to (for a method call), or the path a signal is being emitted from (for a signal).
Returns false if not enough memory.
/* * call-seq: * set_path(object_path) => true|false * * Sets the object path this message is being sent to (for a method call), or * the path a signal is being emitted from (for a signal). * * Returns +false+ if not enough memory. */ static VALUE cDBusMessage_set_path(VALUE self, VALUE value) { MESSAGE_STR_SETTER_BODY(path); }
Sets the serial number (see DbusMessage#get_serial) of the message that this message is a reply to.
/* * call-seq: * set_reply_serial(serial) => true * * Sets the serial number (see DbusMessage#get_serial) of the message * that this message is a reply to. */ static VALUE cDBusMessage_set_reply_serial(VALUE self, VALUE serial) { if (!dbus_message_set_reply_serial(MSG_GET(self), NUM2UINT(serial))) return Qfalse; return Qtrue; }
Sets the service sending this message.
Returns false if not enough memory.
/* * call-seq: * set_sender(service) => true|false * * Sets the service sending this message. * * Returns +false+ if not enough memory. */ static VALUE cDBusMessage_set_sender(VALUE self, VALUE value) { MESSAGE_STR_SETTER_BODY(sender); }