Net::DBus::Exporter Methods

From Alteeve Wiki
Jump to navigation Jump to search

 AN!Tools :: Net::DBus Binding Tutorial :: Net::DBus::Exporter Methods

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 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: 

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]);

OR 

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);

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: 

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]);

OR 

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]);

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: 

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]);

OR 

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);

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

# 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", [], []);

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

# 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"]);

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

# 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"]);

Deprecated Method whose parameter is a single string, returning nothing

# 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});

 

Any questions, feedback, advice, complaints or meanderings are welcome.
Alteeve's Niche! Enterprise Support:
Alteeve Support 		Community Support
© Alteeve's Niche! Inc. 1997-2024   Anvil! "Intelligent Availability®" Platform
legal stuff: All info is provided "As-Is". Do not use anything here unless you are willing and able to take responsibility for your own actions.
Retrieved from ‘https://alteeve.com/w/index.php?title=Net::DBus::Exporter_Methods&oldid=455’