Net::DBus Methods

From Alteeve Wiki
Jump to navigation Jump to search

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

find

Usage:

my $bus=Net::DBus->find(%params);

Where '$bus' is a handle to either the 'system' or 'session' bus, as chosen by 'find'.

This attempts to determine which bus, 'system' or 'session', is best to connect to. It does this by examining a few system variables. They are, in order that they are searched:

  • 'DBUS_STARTER_BUS_TYPE'; If defined and equals 'session', it returns a connection to the session bus.
  • 'DBUS_STARTER_BUS_TYPE'; If defined and equals 'system', it returns a connection to the system bus.
  • 'DBUS_SESSION_BUS_ADDRESS'; If exists, returns a connection to the session bus.
  • Failing the above, it returns a connection to the system bus.

system

Usage:

my $bus=Net::DBus->system(%params);

This simply returns a connection to the (default/Freedesktop.org?) DBus 'system' bus. Given that the system bus is available to all programs and users on the system, certain restrictions are in effect.

session

Usage:

my $bus=Net::DBus->session(%params);

This simply returns a connection to the (default/Freedesktop.org?) DBus 'session' bus. This bus is only accessible by the user invoking the connection.

new

Usage:

my $bus=Net::DBus->new($address, %params);

This returns a connection to a specified, user-defined bus. It is used when you want to connect to a bus other than the default 'system' or 'session' bus.

Where; '$address' is the address of a bus to connect to. This value may look like;

  • my $address="unix:abstract=/tmp/dbus-PBFyyuUiVb,guid=191e0a43c3efc222e0818be556d67500"; (connect to a 'session' bus.)
  • my $address="unix:/var/run/dbus/system_bus_socket"; (connect to a 'system' bus.)

get_service

Usage:

my $service=$bus->get_service($name);

This returns a handle to the remote service specified in the '$name' variable.

When the name is not "org.freedesktop.DBus", this method checks to see if the name *doesn't* start with a colon (:). If it doesn't, it tries to see if the owner of the service can be determined using the 'get_service_owner' method. Should that fail, it will try to start the remote service using the 'get_bus_object->StartServiceByName' method and then tries to determine the owner again. Finally, the local list of services are checked for a matching name and, if found, it is returned. If a local service of the given name is not found, 'Net::DBus::RemoteService->new' is called and the returned handle is fed into a local service of the same name and that is returned.

Where; '$name' can be;

  • "org.freedesktop.DBus" which simply returns a connection to the default bus service. (accurate?)
  • A value that does not begin with ':'.
  • (others valid? If so, what restrictions?)

export_service

Usage:

my $service=$bus->export_service($name);

This takes a name and registers a service by that name on the bus. A handle to the new service is returned.

get_bus_object

Usage:

my $object=$bus->get_bus_object;

Returns a handle to the bus object "/org/freedesktop/DBus" provided by the service 'org.freedesktop.DBus'.

  • When would this be used? What about when using a custom bus?

get_unique_name

Usage:

my $name=$bus->get_unique_name;

This returns the unique name of the active client's connection to the bus.

get_service_owner

Usage:

my $name = $bus->get_service_owner($service);

This takes the name of a service and returns the unique name of the client on the bus that owns that service. The method '$bus->GetNameOwner($service);' is called in an 'eval'. If a value is retrieved, it is returned. If an error is raised and the error is "org.freedesktop.DBus.Error.NameHasNoOwner", 'undef' is returned. Otherwise an exception is thrown and the error set by the 'eval' is displayed.

'Typing' Methods

Normally, introspection data is provided by a service so a client will not need to specifically define the type of data being used. If the introspection data is not complete though, you may need to explicitely specify the data typing.

Before you can use any of the following typing methods, you will need to change how you call 'Net::DBus' to explicitly export the typing methods by using 'use Net::DBus (:typing);'.

Please review the List of DBus data types to get a better feel for the various data types and signatures below.

dbus_int16

Usage:

my $typed_value=dbus_int16($value);

Mark a value as being a signed 16-bit integer. Valid values are (+/-) 0 to 65,535.

dbus_uint16

Usage:

my $typed_value=dbus_uint16($value);

Mark a value as being an unsigned 16-bit integer. Valid values are 0 to 65,535.

dbus_int32

Usage:

my $typed_value=dbus_int32($value);

Mark a value as being a signed 32-bit integer. Valid values are (+/-) 0 to 4,294,967,295.

dbus_uint32

Usage:

my $typed_value=dbus_int32($value);

Mark a value as being an unsigned 32-bit integer. Valid values are 0 to 4,294,967,295.

dbus_int64

Usage:

my $typed_value=dbus_int64($value);

Mark a value as being a signed 64-bit integer. Valid values are (+/-) 0 to 18,446,744,073,709,551,616.

dbus_uint64

Usage:

my $typed_value=dbus_int64($value);

Mark a value as being an unsigned 64-bit integer. Valid values are 0 to 18,446,744,073,709,551,616.

dbus_double

Usage:

my $typed_value=dbus_double($value);

Mark a value as being a double-precision IEEE 754 floating point value.

dbus_byte

Usage:

my $typed_value=dbus_byte($value);

Mark a value as being a byte.

dbus_string

Usage:

my $typed_value=dbus_string($value);

Mark a value as being a UTF-8 encoded string. This is generally not needed as Perl's default scalar value is 'string'.

dbus_signature

Usage:

my $typed_value=dbus_signature($value);

Mark a value as being a UTF-8 string whose value is a valid DBus type signature.

dbus_object_path

Usage:

my $typed_value=dbus_object_path($value);

Mark a value as being a UTF-8 string whose value is a valid DBus object path.

dbus_boolean

Usage:

my $typed_value=dbus_boolean($value);

Mark a value as being a boolean value.

dbus_array

Usage:

my $typed_value=dbus_array($value);

Mark a value as being a DBus array.

dbus_struct

Usage:

my $typed_value=dbus_struct($value);

Mark a value as being a DBus structure.

dbus_dict

Usage:

my $typed_value = dbus_dict($value);

Mark a value as being a DBus dictionary.

dbus_variant

Usage:

my $typed_value = dbus_variant($value);

Mark a value as being a DBus variant.

get_connection

Usage:

my $connection=$bus->get_connection;

This returns a handle to the underlying connection object of the '$bus'. Generally speaking, programmers won't need to use this. As such, you should avoid using this call unless you have a good reason to be doing so. - That said, an example of when you might want to this is ... (I think this should be defined, if only "for the record").

  • Calling 'my $name=$bus->get_unique_name;' simply calls '$bus->get_connection->get_unique_name;'.

test

Usage:

my $bus=Net::DBus->test(%params);

This is used for unit testing. It connects to an in-memory bus used for testing purposes.  

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.