Namespace:  com.novell.powersave

@section com.novell.powersave Interface


@subsection Events triggerd by the Powersave Daemon

@strong{Acpi events from /proc/acpi/events}
@itemize
        @item Interface: com.novell.powersave
        @item Member   : "AcpiEvent"
        @item Type     : Signal
@end itemize
0 string (e.g. "button_power")

@strong{Powersave events}
@itemize
        @item Interface: com.novell.powersave
        @item Member   : "PowersaveEvent"
        @item Type     : Signal
@end itemize
0 string ("battery_low")

Possible events:
@itemize
        @item "acadapter.offline"
        @item "acadapter.online"

        @item "button.sleep"
        @item "button.power"
        @item "button.lid.open"
        @item "button.lid.closed"

        @item "temperature.ok"
        @item "temperature.active"
        @item "temperature.passive"
        @item "temperature.hot"
        @item "temperature.critical"

        @item "battery.normal"
        @item "battery.warning"
        @item "battery.low"
        @item "battery.critical"

        @item "battery.info"  (something changed -> remaining percent/time should be reread)

        @item "global.suspend2disk"  (daemon has been asked to suspend and will do so now)
        @item "global.suspend2ram"
        @item "global.standby"
        @item "global.resume.suspend2disk"  (we are back from suspend)
        @item "global.resume.suspend2ram"
        @item "global.resume.standby"

        @item "daemon.start"
        @item "daemon.terminate"

        @item "daemon.scheme.change"  (scheme has been switched -> reread schemes or other info that could have changed)
        @item "other"                 (Not sure now)
@end itemize

@strong{Daemon or script progress (e.g. 'unloading modules 40%)}
@itemize
        @item Interface: com.novell.powersave
        @item Member   : "Progress"
        @item Type     : Signal
@end itemize

Return types:
@itemize
	@item 0 string : Progress description (e.g. "unloading modules...")
	@item 1 int32  : Progress (e.g. "10")
@end itemize

@strong{Simple messages, error messages or notifications}
@itemize
        @item Interface: com.novell.powersave
        @item Member   : "Notification"
        @item Type     : Signal
@end itemize
0 string (e.g. "Unable to unload module.")

D-BUS Example:

    signal sender=:1.5 -> dest=(null destination) interface=com.novell.powersave; member=acpi_event
    0 string "button.power"

    When an event occurs the clients may want to use the Request interface to reread
    specific values (e.g. request "rem_charg_time_battery" after a event "battery.info",
                     or   request "schemes"                after a event "daemon.scheme.changed"


@section IV. Client Requests (Client -(request)-> Daemon -(response)-> Client)

 -> All requests do not have any parameters.

@strong{Get all Powersave schemes}
@itemize
        @item Interface: com.novell.powersave
        @item Member   : "SchemesGet"
        @item Type     : Method call with return
@end itemize

Return types:
@itemize
        @item 0 string : array containing all available schemes
        @item 1 uint8_t: index of current active scheme (use order of sent string array)
        @item 2 uint8_t: index of battery scheme (use order of sent string array)
        @item 3 uint8_t: index of AC scheme (use order of sent string array)
@end itemize

@strong{Get a specific scheme description}
@itemize
        @item Interface: com.novell.powersave
        @item Member   : "SchemesGetDescription"
        @item Type     : Method call with return
@end itemize

Param:
@itemize
        @item 0 string : string has to match a scheme name.
@end itemize

Return types:
@itemize
        @item 0 string : the requested scheme description
@end itemize


@section Daemon Actions (Client -(action)-> Daemon)

@strong{Check whether daemon is up and replies}
@itemize
        @item Interface: com.novell.powersave
        @item Member   : "Ping"
        @item Type     : Method call with return
@end itemize

@strong{Set machine into suspend to disk mode}
@itemize
        @item Interface: com.novell.powersave
        @item Member   : "SuspendToDisk"
        @item Type     : Method call with return
@end itemize

@strong{Set machine into suspend to ram mode}
@itemize
        @item Interface: com.novell.powersave
        @item Member   : "SuspendToRam"
        @item Type     : Method call with return
@end itemize

@strong{Set machine into standby mode}
@itemize
        @item Interface: com.novell.powersave
        @item Member   : "Standby"
        @item Type     : Method call with return
@end itemize

@strong{Enabled a single CPU}
@itemize
        @item Interface: com.novell.powersave
        @item Member   : "CpufreqCPUEnable"
        @item Type     : Method call with return
@end itemize

Param:
@itemize
        @item 0 int : the CPU number to enable starting from 0
@end itemize

@strong{Disable a single CPU}
@itemize
        @item Interface: com.novell.powersave
        @item Member   : "CpufreqCPUDisable"
        @item Type     : Method call with return
@end itemize

Param:
@itemize
        @item 0 int : the CPU number to disable starting from 0.
                      CPU 0 can't be disabled ATM because it runs the
                      main timer
@end itemize

@strong{Set a powersave scheme}
@itemize
        @item Interface: com.novell.powersave
        @item Member   : "SchemesSet"
        @item Type     : Method call with return
@end itemize

Param:
@itemize
        @item 0 string : string has to match a scheme name. scheme names can be requested (see above)
@end itemize

@strong{Notify connected clients of any progress going on}

@section Return Messages

All calls to the bus get a return/error message replied.

Return messages include following types:

@itemize
        @item 0 uint_16 : Error ID
        @item 0 string  : Error message
@end itemize

The error ids can be found in powerlib.h as defines.

@subsection If no error occured the return message includes (normal message):

@itemize
        @item 0 Error ID      : REPLY_SUCCESS
        @item 1 Error message : "success"
@end itemize

If an error happens the message will be an error reply (as specified by dbus).
Following errors can be checked for all method calls/signals:

General Error
@itemize
        @item 0 Error ID      : REPLY_GENERAL_ERROR
        @item 1 Error message : "general error"
@end itemize

No connection Error (The daemon is probably not running)
@itemize
        @item 0 Error ID      : REPLY_CONNECTION
        @item 1 Error message : "no connection"
@end itemize

No rights Error (The client is not allowed to speak with the daemon)
@itemize
        @item 0 Error ID      : REPLY_NO_RIGHTS
        @item 1 Error message : "no rights"
@end itemize

Invalid Paramet (The client sent bullshit)
@itemize
        @item 0 Error ID      : REPLY_INVALID_PARAM
        @item 1 Error message : "invalid param"
@end itemize


Following request/actions may return specialised errors:


@subsection Specialised Error Replies

Following errors may occur on some actions/requests
and must be checked by the client if such a action/request
is made:

@enumerate
        @item Not supported (by HW):

        @itemize
                @item 0 : REPLY_HW_NOT_SUPPORTED
                @item 1 : "not supported"
        @end itemize

        Interface: com.novell.powersave
        @itemize
                 @item Member   : "SuspendToDisk"
                          @item Member   : "SuspendToRam"
                          @item Member   : "Standby"
        @end itemize

        @item Already set

        @itemize
                @item 0        : REPLY_ALREADY_SET
                @item 1        : "already set"
        @end itemize

        @item Does not exist

        @itemize
                @item 0        : REPLY_INVALID_METHOD
                @item 1        : "does not exist"
        @end itemize

        Interface: com.novell.powersave
        @itemize
                @item Member   : "SchemesSet"
        @end itemize

@end enumerate