Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Net::DBus::Exporter(3)User Contributed Perl DocumentatioNet::DBus::Exporter(3)

NAME
       Net::DBus::Exporter - Export object methods and signals to the bus

SYNOPSIS
	 # Define a new	package	for the	object we're going
	 # to export
	 package Demo::HelloWorld;

	 # Specify the main interface provided by our object
	 use Net::DBus::Exporter qw(org.example.demo.Greeter);

	 # We're going to be a DBus object
	 use base qw(Net::DBus::Object);

	 # Ensure only explicitly exported methods can be invoked
	 dbus_strict_exports;

	 # Export a 'Greeting' signal taking a stringl string parameter
	 dbus_signal("Greeting", ["string"]);

	 # Export 'Hello' as a method accepting	a single string
	 # parameter, and returning a single string value
	 dbus_method("Hello", ["string"], ["string"]);

	 # Export 'Goodbye' as a method	accepting a single string
	 # parameter, and returning a single string, but put it
	 # in the 'org.exaple.demo.Farewell' interface
	 dbus_method("Goodbye",	["string"], ["string"],	"org.example.demo.Farewell");

DESCRIPTION
       The "Net::DBus::Exporter" module	is used	to export methods and signals
       defined in an object to the message bus.	Since Perl is a	loosely	typed
       language	it is not possible to automatically determine correct type
       information for methods to be exported.	Thus when sub-classing
       Net::DBus::Object, this package will provide the	type information for
       methods and signals.

       When importing this package, an optional	argument can be	supplied to
       specify the default interface name to associate with methods and
       signals,	for which an explicit interface	is not specified.  Thus	in the
       common case of objects only providing a single interface, this removes
       the need	to repeat the interface	name against each method exported.

SCALAR TYPES
       When specifying scalar data types for parameters	and return values, the
       following string	constants must be used to denote the data type.	When
       values corresponding to these types are (un)marshalled they are
       represented as the Perl SCALAR data type	(see perldata).

       "string"
	   A UTF-8 string of characters

       "int16"
	   A 16-bit signed integer

       "uint16"
	   A 16-bit unsigned integer

       "int32"
	   A 32-bit signed integer

       "uint32"
	   A 32-bit unsigned integer

       "int64"
	   A 64-bit signed integer. NB,	this type is not supported by many
	   builds of Perl on 32-bit platforms, so if used, your	data is	liable
	   to be truncated at 32-bits.

       "uint64"
	   A 64-bit unsigned integer. NB, this type is not supported by	many
	   builds of Perl on 32-bit platforms, so if used, your	data is	liable
	   to be truncated at 32-bits.

       "byte"
	   A single 8-bit byte

       "bool"
	   A boolean value

       "double"
	   An IEEE double-precision floating point

COMPOUND TYPES
       When specifying compound	data types for parameters and return values,
       an array	reference must be used,	with the first element being the name
       of the compound type.

       ["array", ARRAY-TYPE]
	   An array of values, whose type os "ARRAY-TYPE". The "ARRAY-TYPE"
	   can be either a scalar type name, or	a nested compound type.	When
	   values corresponding	to the array type are (un)marshalled, they are
	   represented as the Perl ARRAY data type (see	perldata). If, for
	   example, a method was declared to have a single parameter with the
	   type, ["array", "string"], then when	calling	the method one would
	   provide a array reference of	strings:

	       $object->hello(["John", "Doe"])

       ["dict",	KEY-TYPE, VALUE-TYPE]
	   A dictionary	of values, more	commonly known as a hash table.	The
	   "KEY-TYPE" is the name of the scalar	data type used for the
	   dictionary keys. The	"VALUE-TYPE" is	the name of the	scalar,	or
	   compound data type used for the dictionary values. When values
	   corresponding to the	dict type are (un)marshalled, they are
	   represented as the Perl HASH	data type (see perldata). If, for
	   example, a method was declared to have a single parameter with the
	   type	["dict", "string", "string"], then when	calling	the method one
	   would provide a hash	reference of strings,

	      $object->hello({forename => "John", surname => "Doe"});

       ["struct", VALUE-TYPE-1,	VALUE-TYPE-2]
	   A structure of values, best thought of as a variation on the	array
	   type	where the elements can vary. Many languages have an explicit
	   name	associated with	each value, but	since Perl does	not have a
	   native representation of structures,	they are represented by	the
	   LIST	data type. If, for exaple, a method was	declared to have a
	   single parameter with the type ["struct", "string", "string"],
	   corresponding to the	C structure

	       struct {
		 char *forename;
		 char *surname;
	       } name;

	   then, when calling the method one would provide an array refernce
	   with	the values orded to match the structure

	      $object->hello(["John", "Doe"]);

MAGIC TYPES
       When specifying introspection data for an exported service, there are a
       couple of so called "magic" types. Parameters declared as magic types
       are not visible to clients, but instead their values are	provided
       automatically by	the server side	bindings. One use of magic types is to
       get an extra parameter passed with the unique name of the caller
       invoking	the method.

       "caller"
	   The value passed in is the unique name of the caller	of the method.
	   Unique names	are strings automatically assigned to client
	   connections by the bus daemon, for example ':1.15'

       "serial"
	   The value passed in is an integer within the	scope of a caller,
	   which increments on every method call.

ANNOTATIONS
       When exporting methods, signals & properties, in	addition to the	core
       data typing information,	a number of metadata annotations are possible.
       These are specified by passing a	hash reference with the	desired	keys
       as the last parameter when defining the export. The following
       annotations are currently supported

       no_return
	   Indicate that this method does not return any value,	and thus no
	   reply message should	be sent	over the wire, likewise	informing the
	   clients not to expect / wait	for a reply message

       deprecated
	   Indicate that use of	this method/signal/property is discouraged,
	   and it may disappear	altogether in a	future release.	Clients	will
	   typically print out a warning message when a	deprecated
	   method/signal/property is used.

       param_names
	   An array of strings specifying names	for the	input parameters of
	   the method or signal. If omitted, no	names will be assigned.

       return_names
	   An array of strings specifying names	for the	return parameters of
	   the method. If omitted, no names will be assigned.

       strict_exceptions
	   Exceptions thrown by	this method which are not of type
	   Net::DBus::Error will not be	caught and converted to	D-Bus errors.
	   They	will be	rethrown and continue up the stack until something
	   else	catches	them (or the process dies).

METHODS
       dbus_method($name, $params, $returns, [\%annotations]);
       dbus_method($name, $params, $returns, $interface, [\%annotations]);
	   Exports a method called $name, having parameters whose types	are
	   defined by $params, and returning values whose types	are defined by
	   $returns. If	the $interface parameter is provided, then the method
	   is associated with that interface, otherwise	the default interface
	   for the calling package is used. The	value for the $params
	   parameter should be an array	reference with each element defining
	   the data type of a parameter	to the method. Likewise, the $returns
	   parameter should be an array	reference with each element defining
	   the data type of a return value. If it not possible to export a
	   method which	accepts	a variable number of parameters, or returns a
	   variable number of values.

       dbus_no_strict_exports();
	   If a	object is using	the Exporter to	generate DBus introspection
	   data, the default behaviour is to only allow	invocation of methods
	   which have been explicitly exported.

	   To allow clients to access methods which have not been explicitly
	   exported, call "dbus_no_strict_exports". NB,	doing this may be a
	   security risk if you	have methods considered	to be "private"	for
	   internal use	only. As such this method should not normally be used.
	   It is here only to allow switching export behaviour to match
	   earlier releases.

       dbus_property($name, $type, $access, [\%attributes]);
       dbus_property($name, $type, $access, $interface,	[\%attributes]);
	   Exports a property called $name, whose data type is $type.  If the
	   $interface parameter	is provided, then the property is associated
	   with	that interface,	otherwise the default interface	for the
	   calling package is used.

       dbus_signal($name, $params, [\%attributes]);
       dbus_signal($name, $params, $interface, [\%attributes]);
	   Exports a signal called $name, having parameters whose types	are
	   defined by $params. If the $interface parameter is provided,	then
	   the signal is associated with that interface, otherwise the default
	   interface for the calling package is	used. The value	for the
	   $params parameter should be an array	reference with each element
	   defining the	data type of a parameter to the	signal.	Signals	do not
	   have	return values. It not possible to export a signal which	has a
	   variable number of parameters.

EXAMPLES
       No parameters, no return	values
	   A method which simply prints	"Hello World" each time	its called

	      sub Hello	{
		  my $self = shift;
		  print	"Hello World\n";
	      }

	      dbus_method("Hello", [], []);

       One string parameter, returning an boolean value
	   A method which accepts a process name, issues the killall command
	   on it, and returns a	boolean	value to indicate whether it was
	   successful.

	      sub KillAll {
		  my $self = shift;
		  my $processname = shift;
		  my $ret  = system("killall $processname");
		  return $ret == 0 ? 1 : 0;
	      }

	      dbus_method("KillAll", ["string"], ["bool"]);

       One list	of strings parameter, returning	a dictionary
	   A method which accepts a list of files names, stats them, and
	   returns a dictionary	containing the last modification times.

	       sub LastModified	{
		  my $self = shift;
		  my $files = shift;

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

	       dbus_method("LastModified", ["array", "string"],	["dict", "string", "int32"]);

       Annotating methods with metdata
	   A method which is targeted for removal, and also does not return
	   any value

	       sub PlayMP3 {
		   my $self = shift;
		   my $track = shift;

		   system "mpg123 $track &";
	       }

	       dbus_method("PlayMP3", ["string"], [], {	deprecated => 1, no_return => 1	});

	   Or giving names to input parameters:

	       sub PlayMP3 {
		   my $self = shift;
		   my $track = shift;

		   system "mpg123 $track &";
	       }

	       dbus_method("PlayMP3", ["string"], [], {	param_names => ["track"] });

AUTHOR
       Daniel P. Berrange <dan@berrange.com>

COPYRIGHT
       Copright	(C) 2004-2011, Daniel Berrange.

SEE ALSO
       Net::DBus::Object, Net::DBus::Binding::Introspector

perl v5.24.1			  2015-03-16		Net::DBus::Exporter(3)

NAME | SYNOPSIS | DESCRIPTION | SCALAR TYPES | COMPOUND TYPES | MAGIC TYPES | ANNOTATIONS | METHODS | EXAMPLES | AUTHOR | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Net::DBus::Exporter&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help