Details on the information required to replace the tklock (touchscreen/key lock) systemui plugin

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.

On 5 July 2011 13:18, Jonathan Wilson <jfwfreo@tpgi.com.au> wrote:

[snip]

> 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.

TKLOCK_ENABLE was used for the tklock in earlier versions of Maemo
(where you'd press the power button followed by center button to unlock).

> 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 flicker key is the lock key available on the N810 and N900; the
770 and N800 doesn't have one.
Called flicker because it's not a slider key -- it "flickers" back.

And indeed these parameters are ignored.


Regards: David