[maemo-developers] Details on the information required to replace the tklock (touchscreen/key lock) systemui plugin

[From: Jonathan Wilson]

The information here references this header file
http://www.cncmods.net/files/systemui.h

It assumes you are familiar with dbus, glib and gconf.
Where I refer to "the code" in these notes, unless otherwise specified, I 
mean the source code to various versions of mce as published online in 
various places

All systemui plugins go in the /usr/lib/systemui folder and are named 
libsystemuiplugin_blah.so. The stock tklock plugin is named 
libsystemuiplugin_tklock.so.

All systemui plugins link to the systemui binary and call functions 
contained within it (my gcc-fu isn't up to code so I dont know exactly how 
one would go about doing that in scratchbox)

Systemui plugins export 2 functions
plugin_init is called when systemui starts up and plugin_close is called 
when it shuts down.
Their prototypes match what is given in systemui.h

The tklock plugin plugin_init function registers 2 systemui handlers using 
systemui_add_handler and also registers a dbus signal handler for the 
signal display_status_ind sent by mce (documentation for the 
display_status_ind dbus call is in the mce-dev documentation)
The plugin_close function uses systemui_remove_handler to remove the 2 
handlers.

The 2 handlers match to dbus messages sent by mce to systemui (which then 
calls the registered handlers for those messages)
Specifically, handlers are registered for SYSTEMUI_TKLOCK_OPEN_REQ and 
SYSTEMUI_TKLOCK_CLOSE_REQ
The prototype of a callback function matches the typedef in systemui.h
The argarray is a GArray containing instances of type dbustype (not 
pointers to dbustype structures but actual structures one after the other)

With regards to the dbustype structure (specifically as used for the 
returntype parameter), the unk1 and unk2 fields should be left alone. The 
type field contains a 32-bit integer corresponding to the relavent dbus 
type character such as 's' or 'u' or 'b'.

the value field contains the value. If the dbus type character is 's', the 
value field is a char * pointer to the string, if it is 'u', the value 
field is an int, if it is 'b', the value field is a single byte boolean value.

Also, the return type of the callback function should be a dbus type.

The entries in the system_ui_data parameter should be used when referencing 
dbus, gconf etc (i.e. fields like gc_client, dbusconnection etc)

Both of the systemui dbus handlers get passed 4 string parameters as their 
first 4 arguments, these are used for the callback mechanism (along with 
the systemui_check_set_callback, systemui_do_callback and 
systemui_free_callback functions which will be mentioned later)

The SYSTEMUI_TKLOCK_OPEN_REQ handler gets passed a uint argument for the 
lockscreen mode, can be TKLOCK_ENABLE, TKLOCK_ONEINPUT or 
TKLOCK_ENABLE_VISUAL. TKLOCK_ONEINPUT is for the blank screen lock mode 
(called "event eater mode" in the code) and TKLOCK_ENABLE_VISUAL is for the 
slide to unlock screen. Not sure what TKLOCK_ENABLE is for exactly.

The second parameter is a boolean argument labeled "silent" by the code. 
The code says "true = disable infoprints, false = enable infoprints". The 
third parameter is a flag that seems to indicate if there is a "flicker 
key" (whatever that is). Both the second and third parameters seem to be 
ignored by the stock tklock plugin.

The SYSTEMUI_TKLOCK_CLOSE_REQ handler gets passed a single bool argument. 
This is the same "silent" value as above and is also ignored by the stock 
tklock plugin.

systemui_check_plugin_arguments is used to check the passed in arguments. 
Pass it the GArray from the callback, an array of 32-bit ints containing 
the arguments (NOT including the first 4 string arguments). So for the 
tklock_open callback, you would pass in 'u','b','b' (all as 32-bit ints 
obviously) and a count.
The return value of systemui_check_plugin_arguments is 0 for failure, 1 for 
success.

Here is what the tklock_close handler does:
Calls check_plugin_arguments to verify the plugin arguments.
Calls systemui_free_callback to free the callback arguments stored earlier 
by a call to systemui_check_set_callback.
Calls some functions to shut down the lockscreen logic.
then returns 'v' as its return value and does not set returntype parameter.

The tklock_open handler calls check_plugin_arguments to verify the plugin 
arguments, it also calls functions to create the appropriate lock handler 
based on the mode. And it calls systemui_check_set_callback to store the 
callback handler details. It sets returntype.type to 'i' and returns 'i'. 
It also sets returntype.value to either -2 or -3 (not sure if the values 
matter)

systemui_do_callback is called passing in a member of the tklock_status 
enum as the callbackarg parameter.

Other things the code does:
Registers a handler for the dbus signal com.nokia.clockd /com/nokia/clockd 
time_changed (used to update the time on the lock screen)

Triggers the dbus signal com.nokia.tklock.signal /com/nokia/tklock/signal 
mm_key_press. Unsure what this signal is for but it gets sent to the volume 
status menu item.

Sends the mce dbus message req_display_state_on

Sends the mce dbus message req_tklock_mode_change with the value "unlocked"

Uses sqlite3 to read from notifications.db to calculate the notification 
value for the lockscreen.

Passes this query to sqlite3
SELECT H.value, H2.value, COUNT(*)   FROM notifications N, hints H, hints 
H2 WHERE N.id=H.nid AND H.id='category' and H2.id = 'time' and H2.nid = 
H.nid GROUP BY  H.value ORDER BY H2.value;
The callback handler for the sqlite3 query references the strings
sms-message
auth-request
chat-invitation
missed-call
email-message
voice-mail

Calls various gtk/gdk grab functions to grab the screen/keyboard.

Uses ipm_show_window and ipm_hide_window to show/hide the relavent windows. 
(these functions somehow involve the "_HILDON_STACKING_LAYER" atom, 
whatever it is)

reads /apps/clock/time-format from gconf

uses /etc/hildon/theme/backgrounds/lockslider.png for the lockslider code

references the atoms "_HILDON_PORTRAIT_MODE_SUPPORT", 
"_HILDON_PORTRAIT_MODE_REQUEST", "_HILDON_STACKING_LAYER", 
"_HILDON_WM_ACTION_NO_TRANSITIONS", "_NET_WM_STATE" and 
"_NET_WM_STATE_FULLSCREEN"

hooks up signals for map-event, button-press-event, button-release-event, 
change-value, value-changed, key-press-event (on 2 different objects) and 
key-release-event.

uses one of the following as an icon name:
tasklaunch_sms_chat
tasklaunch_authorization_response
general_chatroom_invitation
general_application_call
general_email
tasklaunch_voice_mail

obtains the following strings from dcgettext
wdgt_va_12h_time_am
wdgt_va_date_long
wdgt_va_12h_time_pm
wdgt_va_24h_time
secu_swipe_to_unlock

If anyone has any questions about this, if you have any further information 
related to this or any corrections, please let me know. I would also 
appreciate a ping if you do anything with this info.