osso.Context
The LibOSSO Context object.
Constructor
Creates a new osso.Context. Each application can have only one osso.Context.
osso.Context(application, version, activation)
|
|
|---|---|
application |
The name of the application. This name forms the last part of the default (D-BUS) service name of the application. The only valid characters that the name may contain are letters a-z and the underscore '_'. |
version |
The version string of the application. It must be comparable with strcmp(). |
activation |
If this is True, then the library assumes that the application binary has been launched by the D-BUS daemon,
and thus will connect to the D-BUS activation bus (the D-BUS bus where the D-BUS message that resulted in
auto-activation of the application came -- either the session or system bus). This parameter should always
be False and considered obsolete, because otherwise LibOSSO might behave strangely since it normally uses
both session and system bus. |
| Returns | A context to use in later calls to this library. None is returned if an error happened. |
Methods
Remote Procedure Calls
These methods provide wrappers for D-BUS message passing.
rpc_run
This function calls an RPC function of an other application. This call is blocking. If the application providing the function is not already running, it will be started by the D-BUS auto-activation mechanism.
osso.Context.rpc_run(service, object_path, interface, method, rpc_args = (), wait_reply = False, system_bus = False)
|
|
|---|---|
service |
The service name of the remote service, e.g. "com.nokia.application". |
object_path |
The object path of the remote object. |
interface |
The interface that the RPC function belongs to. |
method |
The RPC function to call. |
rpc_args (optional) |
Tuple containing the RPC arguments, if it has any. No arguments are sent by default. |
wait_reply (optional) |
Whether a reply (return value) is being expected or not. Default value is False. |
system_bus (optional) |
Whether the RPC call should be sent on the system bus or not. Default value is False. |
rpc_run_with_defaults
This method is a wrapper for osso.Context.rpc_run. It calls an RPC function of an other
application. This call is blocking. The service name of the other application is "com.nokia.A",
where A is the application parameter passed to this function. Similarly, the object path is
"/com/nokia/A", and the interface "com.nokia.A". If the application providing the
service is not already running, it will be started by the D-BUS auto-activation mechanism.
osso.Context.rpc_run_with_defaults(application, method, rpc_args = (), wait_reply = False)
|
|
|---|---|
application |
The name of the remote application. |
method |
The RPC function to call. |
rpc_args (optional) |
Tuple containing the RPC arguments, if it has any. No arguments are sent by default. |
wait_reply (optional) |
Whether a reply (return value) is being expected or not. Default value is False. |
rpc_async_run
This method calls an RPC function of an other application. This call is non-blocking; a callback function is registered for the return value of the called RPC function. If the application providing the service is not already running, it will be started by the D-BUS auto-activation mechanism.
osso.Context.rpc_async_run(service, object_path, interface, method, callback, user_data = None, rpc_args = ())
|
|
|---|---|
service |
The service name of the remote service, e.g. "com.nokia.application". |
object_path |
The object path of the remote object. |
interface |
The interface that the RPC function belongs to. |
method |
The RPC function to call. |
callback |
A a function to be called when the call returns. If the call times out, callback
will be called with an error generated by the D-BUS library. If this is None, this method
behaves just like osso.Context.rpc_run, with wait_reply set to False. |
user_data (optional) |
Arbitrary application specific object that will be passed to the callback and ignored by LibOSSO. |
rpc_args (optional) |
Tuple containing the RPC arguments, if it has any. No arguments are sent by default. |
rpc_async_run_with_defaults
osso.Context.rpc_async_run_with_defaults(application, method, callback, user_data = None, rpc_args = ())
|
|
|---|---|
application |
The name of the remote application. |
method |
The RPC function to call. |
callback |
A a function to be called when the call returns. If the call times out, callback
will be called with an error generated by the D-BUS library. If this is None, this method
behaves just like osso.Context.rpc_run, with wait_reply set to False. |
user_data (optional) |
Arbitrary application specific object that will be passed to the callback and ignored by LibOSSO. |
rpc_args (optional) |
Tuple containing the RPC arguments, if it has any. No arguments are sent by default. |
set_rpc_callback
This method registers/unregisters a callback function for handling RPC calls to a given object of a service.
The callback function will receive the following parameters: interface, method,
arguments and user_data (in that order).
osso.Context.set_rpc_callback(service, object_path, interface, callback, user_data = None)
|
|
|---|---|
service |
The service name to set up, e.g. "com.nokia.application". |
object_path |
The object path that this object has. |
interface |
The interface that this object implements. |
callback |
The function to register. Use None to unregister. |
user_data (optional) |
Arbitrary application specific object that will be passed to the callback and ignored by LibOSSO. |
set_rpc_default_callback
This method registers a callback function for handling RPC calls to the default service of the application.
The default service is "com.nokia.A", where A is the application's name as given
in the constructor.
The callback function will receive the following parameters: interface, method,
arguments and user_data (in that order).
osso.Context.set_rpc_default_callback(callback, user_data = None)
|
|
|---|---|
callback |
The function to register. Use None to unregister. |
user_data (optional) |
Arbitrary application specific object that will be passed to the callback and ignored by LibOSSO. |
get_rpc_timeout
Return the timeout value used by RPC methods.
osso.Context.get_rpc_timeout()
|
|
|---|---|
| Returns | Timeout value used by RPC methods. |
set_rpc_timeout
Sets the timeout value used by RPC methods.
osso.Context.set_rpc_timeout(timeout)
|
|
|---|---|
timeout |
Timeout value used by RPC methods. |
Applications
application_top
This method tops an application (i.e. brings it to the foreground). If the application is not already running, D-BUS will launch it via the auto-activation mechanism. By using this method, only one instance of the application will be running at any given time. If the application is already running, this method will only bring it to the foreground.
osso.Context.application_top(application, arguments)
|
|
|---|---|
application |
The name of the application to top. |
arguments |
This string lists some parameters for the application. It can be used to give the names of the files to
open, etc. If no arguments are to be passed, this can be None. |
Autosaving
How to use autosave:
The application registers callback function(s) that is/are called by LibOSSO to save the user
data (such as an unsaved document). Whenever the user data changes, the application calls
osso.Context.userdata_changed() to tell LibOSSO that the callback(s) should be
called in the future.
LibOSSO will call the callback(s) when:
- A "dirty data" timer in Libosso expires.
- LibOSSO gets a message from the system that unsaved user data should be saved (e.g. at shutdown).
The application should call osso.Context.force_autosave() whenever it is switched to the
background (untopped).
After the autosave callbacks have been called, the timer inside LibOSSO is reset and the application
needs to call osso.Context.userdata_changed() again when it has new "dirty" user data.
set_autosave_callback
This method registers an autosave callback function.
osso.Context.set_autosave_callback(callback, user_data = None)
|
|
|---|---|
callback |
The callback function. |
user_data (optional) |
Arbitrary application specific object that will be passed to the callback and ignored by LibOSSO. |
userdata_changed
This method is called by the application when the user data has been changed, so that LibOSSO knows that a call to the autosave callback is needed in the future to save the user data. The dirty state will be cleared every time the application's autosave callback function is called.
osso.Context.userdata_changed()
|
|---|
force_autosave
This method forces a call to the application's autosave function, and resets the autosave timeout. The application should call this method whenever it is switched to background (untopped).
osso.Context.force_autosave()
|
|---|
get_name
Returns the application name.
osso.Context.get_name()
|
|
|---|---|
| Returns | Application's name. |
get_version
Returns the application version.
osso.Context.get_version()
|
|
|---|---|
| Returns | Application's version. |
Statusbar
statusbar_send_event
This method sends a statusbar event notification over the D-BUS. If the applet is not loaded, the statusbar application will load it.
osso.Context.statusbar_send_event(name, int_arg1, int_arg2, string_arg3)
|
|
|---|---|
name |
The name of the applet that should receive the event. |
int_arg1 |
This is the first argument of the event. It's interpretation depends on event_type. |
int_arg2 |
This is the second argument of the event. It's interpretation depends on event_type. |
string_arg3 |
This is the third argument of the event. It's interpretation depends on event_type.
None can be used here. |
Time
set_time_notification_callback
This method registers a callback that is called whenever the time is changed with this library.
osso.Context.set_time_notification_callback(callback, user_data = None)
|
|
|---|---|
callback |
Function that is called when the system time is changed. |
user_data |
Arbitrary application specific object that will be passed to the callback and ignored by LibOSSO. |
set_time
This method sets the system and hardware time, and notifies about the changing of time over the D-BUS system
bus. Notice: does not currently change the time. The time_sequence parameter is a sequence with 9 elements
(like sequences returned by time standard Python module). These elements are (year, mon, month_day, hour,
min, sec, week_day, year_day, is_daylight_saving).
osso.Context.set_time(time_sequence)
|
|
|---|---|
time_sequence |
A time sequence |
System Notification
system_note_dialog
This method will request that a system note (a window that is modal to the whole system) is shown.
The note has a single OK button. This function enables non-GUI programs to show some information to the
user. Applications that do have a GUI should not use this function but the hildon.Note widget directly.
osso.Context.system_note_dialog(message, type = 'notice')
|
|
|---|---|
message |
The contents for the system note. |
type (optional) |
The type of system note. Can be 'warning', 'error', 'wait' or 'notice'. |
system_note_infoprint
This function requests that the statusbar shows an infoprint (aka information banner). This allows non-GUI applications to display some information to the user. Applications that do have a GUI should not use this function.
osso.Context.system_note_infoprint(message)
|
|
|---|---|
message |
The text to display on the infoprint. |
State Saving
State saving functionality is provided for applications as a convenient way of storing and retrieving GUI state information (e.g. the view to the last open document, scroll bar position). The information saved by using these functions does not survive over power off of the device, so other means need to be used to save e.g. the document that the user was writing (see Autosaving methods). The application should load the state information during startup in order to present the user with the previous GUI state from the start. No automatic saving of GUI state is done; it is left as responsibility of the application to call the appropriate Libosso function to do it.
The new osso.Context.state_read() and osso.Context.state_write()
methods take care of state data reading and writing. The only limitation is that only a
fixed-size contiguous memory area can be stored.
One particular version (the version is given to osso.Context constructor)
of the application can have only one state file.
state_write
This method writes a state object to disk. Any existing files will be overwritten.
osso.Context.state_write(object)
|
|
|---|---|
object |
State object to be written to disk. |
state_read
This method reads a state object from disk.
osso.Context.state_write()
|
|
|---|---|
| Returns | State object that has been written to disk. |
Plugins
plugin_execute
Calls the execute() function of a plugin.
osso.Context.plugin_execute(filename, user_activated, user_data = None)
|
|
|---|---|
filename |
The shared object (.so) file of the plugin. It should include the ".so" prefix, but not a path. |
user_activated |
If the plugin was activated by a user (as opposed to activated by restoring software state), set
to True, else to False. |
user_data (optional) |
The GTK top-level widget. It is needed so that the widgets created by the plugin can be made a child of the main application that utilizes the plugin. |
plugin_save_state
This method is used to tell a plugin to save its state.
osso.Context.plugin_save_state(filename, user_activated, user_data = None)
|
|
|---|---|
filename |
The shared object (.so) file of the plugin. It should include the ".so" prefix, but not a path. |
user_activated |
If the plugin was activated by a user (as opposed to activated by restoring software state), set
to True, else to False. |
user_data (optional) |
Arbitrary application specific object that will be passed to the callback and ignored by LibOSSO. |
Device State
Methods in this group offer a convenient way to receive device status information from lower levels of the system.
display_state_on
Request to turn on the display as if the user had pressed a key or the touch screen. This can be used after completing a long operation such as downloading a large file or after retrieving e-mails.
osso.Context.display_state_on()
|
|---|
display_blanking_pause
Request not to blank the display. This method must be called again within 60 seconds to renew the request. The method is used, for example, by the video player during video playback. Also prevents suspending the device.
osso.Context.display_blanking_pause()
|
|---|
set_device_state_callback
TO DO
MIME Types
set_mime_callback
This method registers a MIME callback function that LibOSSO calls when the user wants the application to open file(s) of a MIME type handled by the application.
The callback function will receive a parameter with a list of URIs and user_data.
osso.Context.set_mime_callback(callback, user_data = None)
|
|
|---|---|
callback |
The callback function to call. None unsets the callback. |
user_data (optional) |
Arbitrary application specific object that will be passed to the callback and ignored by LibOSSO. |
Improve this page