Digimer: Created page with '{{dbtut_header}} = Preface = There are a couple special types that you need to be aware of before you use this module's methods. == MAGIC TYPES == There are a couple of "magi…'

2009-10-12T02:57:32Z

Created page with '{{dbtut_header}} = Preface = There are a couple special types that you need to be aware of before you use this module's methods. == MAGIC TYPES == There are a couple of "magi…'

Páàjì titun

{{dbtut_header}}

= Preface =

There are a couple special types that you need to be aware of before you use this module's methods.

== MAGIC TYPES ==

There are a couple of "magic types" that can be used when specifying introspection data for an exported service. A parameters declared as one of the magic types are not visible to clients. Instead, it's value is provided automatically be the server-side bindings.

For example, you can use a magic type to automatically pass the unique name of the caller to a method.

=== caller ===

This magic type passes in the [[Net::DBus_Binding_Tutorial#Unique_Connection_Name|unique name]] of the caller to the method.

=== serial ===

*MADI: Link 'serial number'
This magic type passes in the [[serial number]] assigned to the caller for the given method call.

== ANNOTATIONS ==

Annotations are [[metadata]] that can be passed to an exported method, signal or property as a hash reference. These indicate certain bits of information about the method being exported when used by a client.

=== no_reply ===

This annotation informs the caller that the method will not be returning any data. In this way, the caller will know not to bother waiting for a reply.

=== deprecated ===

This tells the caller that the use of the method, signal or property is discouraged as the exported object may disappear in a future version. The client should print out a warning when this annotation has been set.

== Properties ==

Properties have an access flag value that indicates if the property value can be read, written or both. The valid values are "read", "write" and "readwrite", respectively.

= Methods =

== dbus_method ==

Usage:
<source lang="perl">
my $name="SomeMethod";
my @params=("[\"array\", \"string\"]", "[\"int32\"]"); # Some type(s) to be accepted by the method...
my @return=("[\"string\"]"); # Some returned type(s)...
my %annotations=(); # Optional. If not used, don't bother including it.
dbus_method($name, \@params, \@returns, [\%annotations]);
</source>
OR
<source lang="perl">
my $name="SomeMethod";
my @params=("[\"unint32\"]"); # Some type(s) to be accepted by the method...
my @return=("[\"string\"]"); # Some returned type(s)...
my $interface="org.example.foo";
my %annotations=(no_reply=>1); # Tell the caller not to wait for a reply.
dbus_method($name, \@params, \@returns, $interface, \%annotations);
</source>

This exports a method called '$name' that accepts data with the type signature(s) in the array '@params' and returns data with the type signature(s) '@return'. The arrays '@params' and '@return' must be passed as references. If you specify any annotations, pass them as a hash reference at the end of the declaration.

In the first example, no '$interface' is specified, so the default one is used. In the second case, an explicit interface is defined so this method will be exported using that interface.

== dbus_signal ==

Usage:
<source lang="perl">
my $name="SomeProperty";
my @params="[\"dict\", \"string\", \"int32\"], [\"string\"]"; # Signal's data type.
my %annotations=(); # Optional. If not used, don't bother including it.
dbus_signal($name, \@params, [\%annotations]);
</source>
OR
<source lang="perl">
my $name="SomeProperty";
my @params="[\"string\"]"; # Signal's data type.
my $interface="org.example.foo";
my %annotations=(); # Optional. If not used, don't bother including it.
dbus_signal($name, \@params, $interface, [\%annotations]);
</source>

This exports a signal called '$name' that emits data with the type signature defined in '@params'.

In the first example, no '$interface' is specified, so the default one is used. In the second case, an explicit interface is defined so this signal will be exported using that interface.

== dbus_property ==

Usage:
<source lang="perl">
my $name="SomeProperty";
my $type="[\"string\"]"; # Property's data type.
my $access="readwrite"; # The access flag.
my %annotations=(); # Optional. If not used, don't bother including it.
dbus_property($name, $type, $access, [\%annotations]);
</source>
OR
<source lang="perl">
my $name="SomeProperty";
my $type="[\"string\"]"; # Property's data type.
my $access="readwrite"; # The access flag.
my $interface="org.example.foo";
my %annotations=(deprecated=>1); # Tell the caller that this property is going away soon.
dbus_property($name, $type, $access, $interface, \%annotations);
</source>

This exports a property called '$name' whose value has the type signature '$type' and has the specified '$access' flag.

In the first example, no '$interface' is specified, so the default one is used. In the second case, an explicit interface is defined so this property will be exported using that interface.

If not specified, the default 'type' is "string" and the default 'access' is "readwrite". Do not leave out 'type' is you are specifying 'access'. Don't leave out either if you are specifying an interface.

= Examples =

== Simple Method, no parameters or returned data ==

<source lang="perl">
# A method that, when called, simply prints "Hello, World!".
sub Hello
{
my $self=shift;
print "Hello, World!\n";
}

# Export the method 'Hello', which takes no data and returns no data.
dbus_export("Hello", [], []);
</source>

== Simple Method, parameter is a single string, return is a boolean ==

<source lang="perl">
# A method that takes a process names, calls 'killall' and returns a boolean
# value indicating success or failure.
sub KillAll
{
my $self=shift;
my $process_name=shift;
my $error=system("killall $process_name");
if ( $error == 0 ) { return(1); } else { return(0); }
}

# Export the method 'KillAll', which takes a 'string' and returns a 'boolean'.
dbus_export("KillAll", ["string"], ["bool"]);
</source>

== Complex Method, parameter is an array of strings, return is a dictionary ==

<source lang="perl">
# A method that takes an array of file names, stats them to get their last
# modified time (in UNIX time), and returns a hash with the file name as the
# key and the modified time as a 32-bit unsigned integer.
sub LastModified
{
my $self=shift;
my $files=shift;

my %mtime=();
foreach my $file (@{$files})
{
$mtime{$file}=(stat $file)[9];
}
return \%mtime;
}

# Export the method 'LastModified', which takes an 'array' and returns a
# 'dict'.
dbus_export("LastModified", ["array", "string"], ["dict", "string", "int32"]);
</source>

== Deprecated Method whose parameter is a single string, returning nothing ==

<source lang="perl">
# This method has been slated for removal. It takes a file name and plays it.
# It does not return anything to the caller.
sub PlayMP3
{
my $self=shift;
my $track=shift;

# Call the 'mpg123' program, telling it to play the song in the $file.
system "mpg123 $track &";
}

# Export this method, but use the annotations to tell the caller that this
# method is deprecated and also to not bother waiting for a reply.
dbus_export("PlayMP3", [""string"], [], {deprecated => 1, no_reply => 1});
</source>

{{footer}}

Net::DBus::Exporter Methods - Revision history

Digimer: Created page with '{{dbtut_header}} = Preface = There are a couple special types that you need to be aware of before you use this module's methods. == MAGIC TYPES == There are a couple of "magi…'