The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Net-Radio-oFono-0.001
River stage one • 1 direct dependent • 2 total dependents
++
/ Net::Radio::oFono

NAME

Net::Radio::oFono - Perl API to oFono

SYNOPSIS

This is the frontend API to communicate with the oFono daemon over DBus.

    use Net::Radio::oFono;

    my $oFono = Net::Radio::oFono->new();
    my @modems = $oFono->get_modems();
    foreach my $modem_path (@modems)
    {
        my $nwreg = $oFono->get_modem_interface("NetworkRegistration");
        if( $nwreg )
        {
            if( $nwreg->GetProperty("Status", 1) eq "registered" )
            {
                say "Network for modem '" . $modem_path . "': ", $nwreg->GetProperty("Name");
            }
            else
            {
                say "Network for modem '" . $modem_path . "' is in status ", $nwreg->GetProperty("Status");
            }
        }
        else
        {
            say "No network registration for modem $modem_path";
        }
    }
    
    # or use the event API
    my $oFono = Net::Radio::oFono->new(
      "ON_NETWORKREGISTRATION_PROPERTY_NAME_CHANGED" => sub {
          my ( $ofono, $event, $info ) = @_;
          my ( $modem_path, $name ) = @$info;
          say "Network for modem '" . $modem_path . "': ", $name;
      },
      ...
    );

INHERITANCE

  Net::Radio::oFono
  ISA Net::Radio::oFono::Helpers::EventMgr

EVENTS

Instances of Net::Radio::oFono can trigger following events (all characters are upper cased):

ON_MODEM_ADDED

Triggered when a new modem is added. On initialization, it is triggered for each found modem.

Parameters:

$modem_path

D-Bus object path to the modem oject.

ON_MODEM_REMOVED

Triggered when a modem is removed. On destrcution, it is triggered for each remaining modem.

Parameters:

$modem_path

D-Bus object path to the modem oject.

ON_MODEM_INTERFACE_ADDED

Triggered when an interface is added to a modem object. Modem interfaces depend on the modem states, for example the SimManager interface is always available when the modem is Powered.

Parameters:

$modem_path

D-Bus object path to the modem oject.

$interface

The name of the propagated interface (eg. SimManager, RadioSettings, ...)

ON_MODEM_INTERFACE_ . $interface . _ADDED

Triggered when an interface is added to a modem object. Modem interfaces depend on the modem states, for example the SimManager interface is always available when the modem is Powered.

The advantage of this event compared to ON_MODEM_INTERFACE_ADDED is the delegation of the dispatching for different interfaces to the EventMgr.

Parameters:

$modem_path

D-Bus object path to the modem oject.

ON_MODEM_INTERFACE_REMOVED

Triggered when an interface is removed from a modem object. Modem interfaces depend on the modem states, for example the SimManager interface is always available when the modem is Powered and will be removed when the modem is turned off.

Parameters:

$modem_path

D-Bus object path to the modem oject.

$interface

The name of the propagated interface (eg. SimManager, RadioSettings, ...)

ON_MODEM_INTERFACE_ . $interface . _REMOVED

Triggered when an interface is removed from a modem object. Modem interfaces depend on the modem states, for example the SimManager interface is always available when the modem is Powered and will be removed when the modem is turned off.

The advantage of this event compared to ON_MODEM_INTERFACE_REMOVED is the delegation of the dispatching for different interfaces to the EventMgr.

Parameters:

$modem_path

D-Bus object path to the modem oject.

ON_ . $interface . _PROPERTY_CHANGED

Triggered when a property of a modem object or modem interface object is changed. Modem is handled as any other interface for this event.

Typical name for such an event is ON_SIMMANAGER_PROPERTY_CHANGED.

Parameters:

$modem_path

D-Bus object path to the modem oject.

$property

Name of the changed property.

ON_ . $interface . _PROPERTY_ . $property . _CHANGED

Triggered when a property of a modem object or modem interface object is changed. Modem is handled as any other interface for this event.

Typical name for such an event is ON_SIMMANAGER_PROPERTY_PINREQUIRED_CHANGED.

The advantage of this event compared to ON_ . $interface . _PROPERTY_CHANGED is the delegation of the dispatching for different properties to the EventMgr.

Parameters:

$modem_path

D-Bus object path to the modem oject.

$property_value

The value of the changed property.

SUBROUTINES/METHODS

new(%events)

Instantiates new oFono frontend accessor, registers specified events and initializes the modem manager. Events between frontend accessor and wrapper classes are separated.

_init()

Initializes the frontend accessor component:

_add_modem

Internal method to properly add a modem to the frontend for accessing it.

Registers the events ON_PROPERTY_CHANGED and ON_PROPERTY_INTERFACES_CHANGED on the created object.

Triggers the event ON_MODEM_ADDED when finished with that procedure.

_remove_modem

Internal method to properly remove a modem from the frontend for accessing it.

Removes all interfaces objects from the modem using "_update_modem_interfaces" mocking and empty interface list and finally destroy the modem object itself.

Triggers ON_MODEM_REMOVED when the procedure has completed.

_update_modem_interfaces

Internal function to adjust the interface objects of a remote modem objects. It iterates over the list of the available interfaces of the "Interfaces" property of the modem object to instantiate a new interface object for newly added ones and removes those objects of interfaces which are removed.

Triggers the events ON_MODEM_INTERFACE_ADDED and ON_MODEM_INTERFACE_ . uc($interface) . _ADDED for each newly instantiated interface. Triggers the events ON_MODEM_INTERFACE_REMOVED and ON_MODEM_INTERFACE_ . uc($interface) . _REMOVED for each interface which was removed.

get_modems(;$force)

Returns the list of object path's for currently known (and instantiated) modem objects.

TODO: implement way to get without Net::DBus::Reactor->main->run() ...

get_modem_interface($modem_path,$interface)

Returns the object for the specified interface on the given modem object. If either the modem device isn't known or the interface isn't available yet, it returns nothing.

get_remote_object($type,$obj_path;$if_name)

Returns the object for the specified remote object on the given object path. Missing $if_name is replaced by $type.

If one of $type, $obj_path or $if_name isn't available, nothing is returned.

on_modem_added

Invoked when the even ON_MODEM_ADDED is triggered by the modem manager and invokes "_add_modem" for the submitted object path.

on_modem_removed

Invoked when the even ON_MODEM_REMOVED is triggered by the modem manager and invokes "_remove_modem" for the submitted object path.

on_modem_interfaces_changed

Triggered when a modem object changes it's list of available interfaces in addition to on_property_changed with Interfaces as name of the changed property.

Updates active interface objects using "_update_modem_interfaces".

on_object_added

Invoked when the even ON_ ... _ADDED is triggered by any modem interface with manager role when an embedded object is added. Triggers event "ON_" . uc($mgr_type) . "_" . uc($mgmt_type) . "_ADDED" with the object path of the created object as parameter.

When a new context is added in ConnectionManager, the event ON_CONNECTIONMANAGER_CONTEXT_ADDED is triggered.

on_object_removed

Invoked when the even ON_ ... _REMOVED is triggered by any modem interface with manager role when an embedded object is removed. Triggers event "ON_" . uc($mgr_type) . "_" . uc($mgmt_type) . "_ADDED" with the object path of the created object as parameter.

When a context is removed from ConnectionManager, the event ON_CONNECTIONMANAGER_CONTEXT_REMOVED is triggered.

on_property_changed

Triggered when a modem object modifies a property.

Triggers ON_ . uc($interface) . _PROPERTY_CHANGED with modem path and property name as parameter as well as ON_ . uc($interface) . _PROPERTY_ . uc($property) . _CHANGED with modem path and property value as parameter.

on_extra_event

Triggered when any managed remote object fires an event which is not usually watched. This event is enriched with some information about the original sender:

  • The name of the event is modified by placing the upper cased basename of the triggering object interface directly behind the leading "ON_".

  • The list of arguments is prepended by the basename of the triggering object and the object path of the triggering object.

Use /get_remote_object($type,$obj_path;$if_name) to get the object instance.

BUGS

Please report any bugs or feature requests to bug-net-radio-ofono at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-Radio-oFono. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

If you think you've found a bug then please read "How to Report Bugs Effectively" by Simon Tatham: http://www.chiark.greenend.org.uk/~sgtatham/bugs.html.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Net::Radio::oFono

You can also look for information at:

Where can I go for help with a concrete version?

Bugs and feature requests are accepted against the latest version only. To get patches for earlier versions, you need to get an agreement with a developer of your choice - who may or not report the issue and a suggested fix upstream (depends on the license you have chosen).

Business support and maintenance

For business support you can contact Jens via his CPAN email address rehsackATcpan.org. Please keep in mind that business support is neither available for free nor are you eligible to receive any support based on the license distributed with this package.

ACKNOWLEDGEMENTS

At first the guys from the oFono-Team shall be named: Marcel Holtmann and Denis Kenzior, the maintainers and all the people named in ofono/AUTHORS. Without their effort, there would no need for a Net::Radio::oFono module.

Further, Peter "ribasushi" Rabbitson helped a lot by providing hints and support how to make this API accessor a valuable CPAN module.

AUTHOR

Jens Rehsack, <rehsack at cpan.org>

LICENSE AND COPYRIGHT

Copyright 2012 Jens Rehsack.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 680:

alternative text '/get_remote_object($type,$obj_path;$if_name)' contains non-escaped | or /