freesmartphone.org Usage Interface

Description

The Usage interface provides access to subsystem resource management. The usage manager keeps track of all users per resource and will enable or disable the associated hardware/software as requested. Before an application can make use of a subsystem, it needs to request the resource first and is only allowed to use it if the request has been granted.

Namespace

org.freesmartphone.Usage

Methods

Signals

Properties

None

Errors

Methods

RegisterResource ( so )

Description: Register yourself as provider for a given resource.

Implementation Note

Providers can chose the name of the resource freely, note that there are some well known names such as:

  • “GSM”,
  • “GPS”,
  • “Bluetooth”,
  • “WiFi”,
  • “Display”,
  • “CPU”.
In any case, only one provider per resource can be registered at a given time.

Parameters:*

s: name The resource name.

o: path The resource path.

UnregisterResource ( s )

Description: Unregister yourself as provider for a given resource.

Implementation Note

Leaving the bus will automatically unregister yourself for all resources you are providing.

Parameters:*

s: name The resource name.

ListResources ( ) → as

Description: List available resources.

Returns:

as: resources An array of resource names.

GetResourcePolicy ( s ) → s

Description: Get the current resource policy for a given resource.

Parameters:*

s: name The resource name.

Returns:

s: policy The resource policy. Expected values are:

  • “disabled” - using this resource is currently not allowed,
  • “auto” - the resource is enabled as long as it is used by at least one client,
  • “enabled” - the resource is enabled even without a client.

SetResourcePolicy ( ss )

Description: Set a new resource policy for a given resource.

Parameters:*

s: name The resource name.

s: policy The new resource policy. See GetResourcePolicy for a list of valid values.

GetResourceState ( s ) → b

Description: Get the current state for a given resource.

Parameters:*

s: name The resource name.

Returns:

b: state The resource state. True if the resource is currently enabled.

GetResourceUsers ( s ) → as

Description: Get the users which currently use a given resource.

Parameters:*

s: name The resource name.

Returns:

as: users An array of bus names using the resource.

RequestResource ( s )

Description: Request occupation of a given resource. An error is returned if the resource was not occupied sucessfully.

Parameters:*

s: name The resource name.

ReleaseResource ( s )

Description: Release a given resource.

Implementation Note

Resources in use get autoreleased when a client leaves the bus.

Parameters:*

s: name The resource name.

Suspend ( )

Description: Triggers a suspend on all managed resources and puts the device into suspend mode. When the device comes back from suspend, all resources are resumed. All Resources need to implement Suspend and Resume if they have anything to prepare / recover on suspend and resume.

Resume ( ss )

Description: Triggers a resume on all managed resources and puts the device into normal mode.

Implementation Note

This method is only useful on systems where a suspend does not halt the main CPU.

Parameters:*

s: source The resume source.

s: reason The resume reason.

Shutdown ( )

Description: Triggers a shutdown of all managed resources and powers the device down.

Reboot ( )

Description: Triggers a reboot of the device.

Signals

ResourceAvailable ( sb )

Description: Sent whenever a resource is added or removed.

Parameters:

s: name The name of the resource.

b: availability The resource availability. True if the resource is currently available.

ResourceChanged ( sba{sv} )

Description: Sent whenever a resource status changes.

Parameters:

s: name The name of the resource.

b: state The resource state. True if the resource is currently enabled.

a{sv}: attributes The new status of the resource. Expected values are:

  • “policy”: The current resource policy
  • “refcount”: The count of clients that have requested the resource
Further information can be part of the properties.

SystemAction ( s )

Description: Sent whenever a system state action is performed.

Parameters:

s: action The name of the action. Expected values are:

  • “suspend”: The system is suspending.
  • “resume”: The system has resumed.
  • “reboot”: The system is rebooting.
  • “shutdown”: The system is shutting down.

Errors

PolicyUnknown

Description: Raised, if the requested policy is unknown.

PolicyDisabled

Description: Raised, if the requested resource is set to policy “disabled”.

ResourceUnknown

Description: Raised, if the requested resource is unknown.

ResourceExists

Description: Raised, if a (new) resource has already been registered.

ResourceInUse

Description: Raised, if the to-be-disabled (by policy) resource is still in use.

UserExists

Description: Raised, if the requested resource has already been requested by the same user.

UserUnknown

Description: Raised, if the to-be-released resource has never been requested by the user.