Namespace:  com.novell.powersave

Interfaces:
        @enumerate
                @item com.novell.powersave.manager
                @item com.novell.powersave.request
                @item com.novell.powersave.action
        @end enumerate 

@section The Manager Interface

The Manager interface is connection oriented Interface.
Clients have to connect (and send their capabilities) to the daemon.

@subsection Initial Connection by a Client at the Powersave Daemon
@itemize
        @item Interface: com.novell.powersave.manager
        @item Member   : "Connect"
        @item Type     : Method call with return
@end itemize
0 capabilities         int32  (sum of CAPABILITY_* defines, see powersave_clientsocket.h)  
       
 -> client connection (message "connect" with the capabilities which can be handle by the connecting client).

 -> return type: boolean (TRUE on successful connection, else: FALSE)

 -> powersaved has to store the D-BUS sender string (e.g. ":1.5") of the "connect" message. Using this information gives the
+possibility to track clients whether they died unexpectedly.

@strong{Depending on the amount of capabilities the client has, the daemon now knows}

@itemize
        @item what events and messages should be sent to the client.
        @item what he can request from the client
        @item what will be processed by the clients (e.g. screensaver capablities, ...)
@end itemize

D-BUS Example:

    signal sender=:1.5 -> dest=(null destination) interface=com.novell.powersave; member=connect

    0 int32 "3"

    11 corresponds to the capabilities CAPABILITY_NOTIFICATIONS and CAPABILITY_SCREENLOCK

@itemize
        @item #define CAPABILITY_NOTIFICATIONS 1
        @item #define CAPABILITY_SCREENLOCK 2
        @item #define CAPABILITY_BRIGHTNESS 4
@end itemize

@subsection Disconnect by a Client
@itemize
        @item Interface: com.novell.powersave.manager
        @item Member   : "Disconnect"
        @item Type     : Signal
@end itemize

D-BUS Example:

    signal sender=:1.5 -> dest=(null destination) interface=com.novell.powersave; member=disconnect

 -> According to the sender of the disconnect signal, the powersave daemon knows which capabilities are no longer available.


@subsection Events triggerd by the Powersave Daemon

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

@strong{Powersave events}
@itemize
        @item Interface: com.novell.powersave.manager
        @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 "processor.performance" (The cpufreq policy changed to performance)
        @item "processor.powersave"
        @item "processor.dynamic"
        @item "processor.busy"        (The processor is not idle anymore)
        @item "processor.idle"        (The processor was idle for the last x seconds (by default 10))
        @item "processor.notify"      (Not sure now)

        @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.manager
        @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.manager
        @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"

 -> according to its capabilities, the client has to set up matches
    in his filter function for the corresponding events triggered by the daemon.

    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)
(Interface: com.novell.powersave.request)

 -> All requests do not have any parameters.

@strong{Get all Powersave schemes}
@itemize
        @item Interface: com.novell.powersave.request
        @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.request
        @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

@strong{Cpu frequency policy}
@itemize
        @item Interface: com.novell.powersave.request
        @item Member   : "CpufreqPolicy"
        @item Type     : Method call with return
@end itemize

Return type:
@itemize
        @item 0 string : ("dynamic", "performance", "powersave")
@end itemize

@strong{Battery status}
@itemize
        @item Interface: com.novell.powersave.request
        @item Member   : "BatteryState"
        @item Type     : Method call with return
@end itemize

Return type:
@itemize
        @item 0 string : ("critical", "low", "warning", "normal", "no battery")
@end itemize

@strong{Ac adapter power}
@itemize
        @item Interface: com.novell.powersave.request
        @item Member   : "AcPower"
        @item Type     : Method call with return
@end itemize

Return type:
@itemize
        @item 0 string : "on", "off", "unknown"
@end itemize

@strong{If suspend to ram is allowed}
@itemize
        @item Interface: com.novell.powersave.request
        @item Member   : "AllowedSuspendToRam"
        @item Type     : Method call with return
@end itemize

Return type:
@itemize
        @item 0 boolean
@end itemize

@strong{If suspend to disk is allowed}
@itemize
        @item Interface: com.novell.powersave.request
        @item Member   : "AllowedSuspendToDisk"
        @item Type     : Method call with return
@end itemize

Return type:
@itemize
        @item 0 boolean
@end itemize

@strong{If standby is allowed}
@itemize
        @item Interface: com.novell.powersave.request
        @item Member   : "AllowedStandby"
        @item Type     : Method call with return
@end itemize

Return type:
@itemize
        @item 0 boolean
@end itemize

@strong{Get current brightness level}
@itemize
        @item Interface: com.novell.powersave.request
        @item Member   : "BrightnessGet"
        @item Type     : Method call with return
@end itemize

Return type:
@itemize
        @item 0 int : the current brightness level
@end itemize

@strong{Get current brightness in percent}
@itemize
        @item Interface: com.novell.powersave.request
        @item Member   : "BrightnessGetPercent"
        @item Type     : Method call with return
@end itemize

Return type:
@itemize
        @item 0 int : the current brightness level in percent
@end itemize

@strong{Get available brightness levels}
@itemize
        @item Interface: com.novell.powersave.request
        @item Member   : "BrightnessLevelsGet"
        @item Type     : Method call with return
@end itemize

Return type:
@itemize
        @item 0 int : value containing the maximum brightness level
@end itemize

@strong{Query list of device classes for runtime power management}
@itemize
        @item Interface: com.novell.powersave.request
        @item Member   : "DpmClassesGet"
        @item Type     : Method call with return
@end itemize

Return type:
@itemize
        @item 0 string : array containing all available classes
@end itemize

@strong{Query list of devices for a specific device class}
@itemize
        @item Interface: com.novell.powersave.request
        @item Member   : "DpmDevicesGet"
        @item Type     : Method call with return
@end itemize

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

Return type:
@itemize
        @item 0 string : array containing all available classes
@end itemize

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

(Interface: com.novell.powersave.action)

@strong{Check whether daemon is up and replies}
@itemize
        @item Interface: com.novell.powersave.action
        @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.action
        @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.action
        @item Member   : "SuspendToRam"
        @item Type     : Method call with return
@end itemize

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

@strong{Set cpu policy to performance}
@itemize
        @item Interface: com.novell.powersave.action
        @item Member   : "CpufreqPerformance"
        @item Type     : Method call with return
@end itemize

@strong{Set cpu policy to powersave}
@itemize
        @item Interface: com.novell.powersave.action
        @item Member   : "CpufreqPowersave"
        @item Type     : Method call with return
@end itemize

@strong{Set cpu policy to dynamic}
@itemize
        @item Interface: com.novell.powersave.action
        @item Member   : "CpufreqDynamic"
        @item Type     : Method call with return
@end itemize

@strong{Enabled a single CPU}
@itemize
        @item Interface: com.novell.powersave.action
        @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.action
        @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.action
        @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{Set brightness level}
@itemize
        @item Interface: com.novell.powersave.action
        @item Member   : "BrightnessSet"
        @item Type     : Method call with return
@end itemize

Param:
@itemize
        @item 0 int : the brightness level to set
@end itemize

@strong{Set brightness level given in percent}
@itemize
        @item Interface: com.novell.powersave.action
        @item Member   : "BrightnessSetPercent"
        @item Type     : Method call with return
@end itemize

Param:
@itemize
        @item 0 int : the brightness level to set in percent
@end itemize

@strong{Set brightness to minimum}
@itemize
        @item Interface: com.novell.powersave.action
        @item Member   : "BrightnessMin"
        @item Type     : Method call with return
@end itemize

@strong{Set brightness to medium}
@itemize
        @item Interface: com.novell.powersave.action
        @item Member   : "BrightnessMed"
        @item Type     : Method call with return
@end itemize

@strong{Set brightness to maximum}
@itemize
        @item Interface: com.novell.powersave.action
        @item Member   : "BrightnessMax"
        @item Type     : Method call with return
@end itemize

@strong{Increase brightness}
@itemize
        @item Interface: com.novell.powersave.action
        @item Member   : "BrightnessUp"
        @item Type     : Method call with return
@end itemize

@strong{Decrease brightness}
@itemize
        @item Interface: com.novell.powersave.action
        @item Member   : "BrightnessDown"
        @item Type     : Method call with return
@end itemize

@strong{Set a devices into powersave mode}
@itemize
        @item Interface: com.novell.powersave.action
        @item Member   : "DpmDevicesSuspend"
        @item Type     : Method call with return
@end itemize

Param:
@itemize
        @item 0 int : the device number to suspend. If not provided, -1 is
		      taken which is the default
@end itemize

@strong{Resume a devices from powersave mode}
@itemize
        @item Interface: com.novell.powersave.action
        @item Member   : "DpmDevicesResume"
        @item Type     : Method call with return
@end itemize

Param:
@itemize
        @item 0 int : the device number to resume. If not provided, -1 is
		      taken which is the default
@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 powersave_dbus.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.action
        @itemize
                 @item Member   : "SuspendToDisk"
                          @item Member   : "SuspendToRam"
                          @item Member   : "Standby"
                          @item Member   : "CpufreqPerformance"
                          @item Member   : "CpufreqPowersave"
                          @item Member   : "CpufreqDynamic"
        @end itemize

        @item Disabled by administrator:

        @itemize
                @item 0 : REPLY_DISABLED
                @item 1 : "disabled"
        @end itemize

        Interface: com.novell.powersave.action
        @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

        Interface: com.novell.powersave.action
        @itemize
                @item Member   : "CpufreqPerformance"
                @item Member   : "CpufreqPowersave"
                @item Member   : "CpufreqDynamic"
        @end itemize


        @item Does not exist

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

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

@end enumerate