================================================================================
ShIniOp.opo: OPL functions for accessing silkscreen icon information.
Version 1.12 (25 Oct 2004)
Noriyuki Mihashi
================================================================================
[Contents]
1. Summary
2. System requiment
3. Usage
4. Functions
5. Note
6. Licences
7. Changes history
1. Summary
This OPL module is made for changing assignment of appication programs to the
silkscreen icons on the Psion's LCD screen. It has a group of functions to
reading or modifying information of silkscreen icons in the system shell.
2. System requirement
This module works on following these machines:
- Psion Series 5
- Psion Series 5mx
- Revo
- netBook
3. Usage
The assignment of applications to the silkscreen icons are saved in a setting
file of the system shell placed to "C:\System\Apps\Shell\Shell.ini". It makes
possible to change these assignment if you modify the setting file and then
restart the system shell.
The information about assignment of applications to silkscreen icons in the
"Shell.ini" file are described below. Functions in this OPL module modifies
application UID in these assignment informations.
Data Length(bytes) Meanings
----------------------------------------------------------------------------
UID1 (0x10000050) 4 Please see the Symbian OS SDK documents.
UID2 (0x100000e4) 4 Please see the Symbian OS SDK documents.
UID3 (0x10000076) 4 Application UID of system shell.
Chacksum of UIDs 4 Please see the Symbian OS SDK documents.
Unknown 4 Please show the Symbian OS SDK documents.
Perhaps the file size coded through following
expression is stored only on right after hard
reset:
( {file size} - 0x2a ) * 0x02
Unknown 4 Please show the Symbian OS SDK documents.
Perhaps a value 0x01 is stored only on right
after hard reset.
Unknown 4 Please show the Symbian OS SDK documents.
Perhaps the file size coded through following
expression is stored onece after preferences
of system shell were changed:
{file size} - 0x2a
Unknown 2 Please show the Symbian OS SDK documents.
It seems that it might be related with file
size.
Unknown 11 Please show the Symbian OS SDK documents.
Unknown (valiable) Please show the Symbian OS SDK documents.
It seems that it takes 11 bytes on right after
hard reset. This block is lost if onece after
preferences of system shell are changed.
Unknown 2 Please show the Symbian OS SDK documents.
Perhaps the offset bytes to trailer from next
address coded through following expression is
stored:
{offset bytes} + 0x40
Preferences 4 Settings in the "Preferences" menu are stored
as sum of following value:
0x00 Never show wallpaper.
0x01 Always show wallpaper.
0x02 Show wallpaper in bookmark folder.
0x10 Show hidden files.
0x20 Not "Show System folder".
0x40 [Fn]+[Enter] to open multi files.
Length of standard 1 String length of the standrd folder's path
folder starting from next byte. The value set to here
is coded through following expression:
{string length} * 4 + 2
Standard folder (valiable) The value set to "Standard folder" in the
dialog opend by "Preferences" menu of the
system shell.
Length of bookmark 1 String length of the bookmark folder's path
folder starting from next byte. The value set to here
is coded through following expression:
{string length} * 4 + 2
Bookmark folder (variable) Bookmark folder's path set by "Set bookmark"
menu of the system shell.
Unknown 4 Please show the Symbian OS SDK documents.
Perhaps the number of standard buttons in the
toolbar is stored.
Unknown 4 Please show the Symbian OS SDK documents.
Number of silkscreen 1 The number of silkscreen icon's information
icon's information through following expression is stored:
{number of icons} * 2
*** Information of the silkscreen icons are start from next byte. There
repeats several blocks of silkscreen icon informations.
a block of silkscreen icon information:
{
Position number 4 Position number of silkscreen icon. Number
starts from 0 (System shell).
On Series 5mx, number 11 is often missed if
the "Web" application (UID:0x10000fc0) is not
installed.
Application UID 4 Application UID assigned to this icon.
Length of caption 1 String length of the caption starting from
next byte. The value set to here is coded
through following expression:
{string length} * 4 + 2
Caption (valiable) Caption of assigned to this icon that is shown
on the "Extras" bar.
}
Length of wallpaper 1 String length of the wallpaper file's path
path starting from next byte. The value set to here
is coded through following expression:
{string length} * 4 + 2
It does not exist in Psion Series 5.
Wallpaper path (valiable) The path of wallpaper file that was set on the
"Preferences" menu of the system shell.
It does not exist in Psion Series 5.
Length of standard 1 String length of standard Agenda file's path
Agenda file path starting from next byte. The value set to here
is coded through following expression:
{string length} * 4 + 2
It exists only in Revo.
Standard Agenda (valiable) The file path of standard Agenda file shown on
file path the "Today view".
It exists only in Revo.
*** Perhaps the trailer block starts from next byte.
Unknown (valiable) Please show the Symbian OS SDK documents.
It seems that it takes 11 bytes on right after
hard reset. This block is lost if onece after
preferences of system shell are changed.
Unknown 20 Please show the Symbian OS SDK documents.
It seems to be a fixed data.
Address of 4 Offset bytes to addess that the preferences
data block settiings are stored from absolute address
0x20.
----------------------------------------------------------------------------
4. Functions
Following these functions are defined in ShIniOp.opo.
PSiVersion%:
It returns version number. $101 means "Version 1.01".
PSiGetAppUidFromFile&:(fname$, pos%)
It gets the application UID assigned to specified position of silkscreen
icon from specified "Shell.ini" file. The first argument "fname$" takes
the path of "Shell.ini" file. The second argument "pos%" is the position
number of silkscreen icon.
It returns application UID if it successed to get. A value 0xffffffff is
returned if it failed.
PSiGetAppCaptionFromFile$:(fname$, pos%, uidp&)
It gets the application caption assigned to specified position of silk-
screen icon from specified "Shell.ini" file. The first argument "fname$"
takes the path of "Shell.ini" file. The second argument "pos%" is the
position number of silkscreen icon. The third one "uidp&" is address of
the long integer variable to store application UID.
It returns caption string and store the application UID to the address of
"uidp&" if it successed to get. An empty string is returned and a value
0xffffffff is set to the address of "uidp&" if it failed to get.
PSiSetAppUidToFile%:(fname$, pos%, uid&)
It overwrites the application UID assigned to specified position of silk-
screen icon in specified "Shell.ini" file. The first argument "fname$"
takes the path of "Shell.ini" file. The second argument "pos%" is the
position number of silkscreen icon. The third one "uid&" is the new appli-
cation UID to overwrite.
It returns a value KTrue% if it success to overwrite. A value Kalse% is
returned if it failed.
PSiOpenShIni%:(fname$)
It opens specified "Shell.ini" file for updating. The argument "fname$" is
the path of "Shell.ini" file.
It returns a file descriptor if it successed to open file.
PSiOpenrShIni%:(fname$)
It opens specified "Shell.ini" file for reading. The argument "fname$" is
the path of "Shell.ini" file.
It returns a file descriptor if it successed to open file.
PSiCloseShIni:(fp%)
It closes the opened "Shell.ini" file. The argument "fp%" is the file
descriptor which was returned from PSiOpenShIni%: or PSiOpenrShIni%:
function.
PSiReadAppUid&:(fp%, no%)
It returns the application UID assigned to specified number of the silk-
screen icon. The first argument "fp%" is the file descriptor of opened
"Shell.ini" file. The second argument "no%" is the position number of
silkscreen icon.
A value 0xffffffff is returned if it failed to read UID. The file pointer
of opened "Shell.ini" file moves to position number of the next silkscreen
icon when it finished to read UID.
PSiReadAppCaption$:(fp%, no%, uidp&)
It gets the application caption assigned to specified number of the silk-
screen icon. The first argument "fp%" is the file descriptor of opened
"Shell.ini" file. The second argument "no%" is the position number of
silkscreen icon. The third argument "uidp&" is address of the long integer
variable to store application UID.
It returns caption string and store the application UID to the address of
"uidp&" if it successed to get. An empty string is returned and a value
0xffffffff is set to the address of "uidp&" if it failed to get. The file
pointer of opened "Shell.ini" file moves to position number of the next
silkscreen icon when it finished to read caption.
PSiWriteAppUid%:(fp%, no%, uid&)
It overwrites the application UID assigned to specified position of silk-
screen icon. The first argument "fp%" is the file descriptor of opened
"Shell.ini" file. The second argument "no%" is the position number of
silkscreen icon. The third argument "uid&" is the new application UID to
overwrite.
It returns a value KTrue% if it success to overwrite. A value Kalse% is
returned if it failed. The file pointer of opened "Shell.ini" file moves
to position number of the next silkscreen icon when it finished to over-
write UID.
PSiReadCurrentAppUid&:(fp%)
It returns a long integer value read from current file position as the
application UID assigned to the silkscreen icon. The argument "fp%" is the
file descriptor of opened "Shell.ini" file.
The file pointer of opened "Shell.ini" file moves to position number of
the next silkscreen icon when it finished to read UID.
PSiReadCurrentAppCaption$:(fp%, uidp&)
It gets the application caption from current silkscreen icon information.
The file pointer must be positioned to the application UID in silkscreen
icon information block. The first argument "fp%" is the file descriptor
of opened "Shell.ini" file. The second argument "uidp&" is address of the
long integer variable to store application UID.
It returns caption string and store the application UID to the address of
"uidp&" if it successed to get. An empty string is returned and a value
0xffffffff is set to the address of "uidp&" if it failed to get. The file
pointer of opened "Shell.ini" file moves to position number of the next
silkscreen icon when it finished to read caption.
PSiWriteCurrentAppUid:(fp%, uid&)
It overwrites a long integer value to current file position as the appli-
cation UID assigned to the silkscreen icon. The first argument "fp%" is
the file descriptor of opened "Shell.ini" file. The second argument "uid&"
is the new application UID to overwrite.
The file pointer of opened "Shell.ini" file moves to position number of
the next silkscreen icon when it finished to overwrite UID.
PSiSeekAppDat%:(fp%, pos%)
It seeks the file pointer of opened "Shell.ini" file to specified position
of the silkscreen icon information. The first argument "fp%" is the file
descriptor of opened "Shell.ini" file. The second argument "pos%" is the
position number of silkscreen icon.
It returns a value KTrue% if it success to seek. A value Kalse% is
returned if it failed. The file pointer of opened "Shell.ini" file is set
to the position of application UID that is assigned to the spicified silk-
screen icon when it finished to seek.
PSiSetHeadOfAppDat&:(fp%)
It seeks the file pointer of opened "Shell.ini" file to the first silk-
screen icon information. The argument "fp%" is the file descriptor of
opened "Shell.ini" file.
It returns zero if it successed to seek. The file pointer of opened
"Shell.ini" file is set to the position of application UID that is
assigned to the first silkscreen icon.
*** This function is remained for compatibility. It is recommended to use
PSiSeekHeadOfAppDat&: instead of this function.
PSiSeekHeadOfAppDat&:(fp%)
It seeks the file pointer of opened "Shell.ini" file to the first silk-
screen icon information. The argument "fp%" is the file descriptor of
opened "Shell.ini" file.
It returns number of silkscreen icon's information. It returns zero if it
failes to seek. The file pointer of opened "Shell.ini" file is set to the
position of application UID that is assigned to the first silkscreen icon.
PSiSeekNextAppDat&:(fp%)
It skips the file pointer of opened "Shell.ini" file to the next silk-
screen icon information. The argument "fp%" is the file descriptor of
opened "Shell.ini" file.
It returns a position number of the next silkscreen icon. The file pointer
of opened "Shell.ini" file is set to the position of application UID that
is assigned to the next silkscreen icon.
PSiReadPosNo&:(fp%)
It reads a long integer value as silkscreen icon's position number from
current file position of opened "Shell.ini" file. The argument "fp%" is
the file descriptor of opened "Shell.ini" file.
It returns a position number of current silkscreen icon and it might be
a next one of previous silkscreen icon's. No more icon remains if the
number read is not a next one. But be careful that the number 11 is often
missed on Series 5mx. The number 12 becomes after 10 if the number 11 is
missed.
The file pointer of opened "Shell.ini" file is set to the position of
application UID that is assigned to the current silkscreen icon when it
finished to read.
PSiReadStr$:(fp%)
It gets a string data from current file position of opened "Shell.ini"
file. The argument "fp%" is the file descriptor of opened "Shell.ini"
file. The file pointer must be placed to the byte that the string length
is stored when this function is called.
It returns a string data read. The file pointer is set to next byte of the
end of string when it finished to read.
PSiSkipStr:(fp%)
It skips a string data at current file position of opened "Shell.ini"
file. The argument "fp%" is the file descriptor of opened "Shell.ini"
file. The file pointer must be placed to the byte that the string length
is stored when this function is called.
The file pointer is set to next byte of the end of string.
PSiReadStrLen%:(fp%)
It returns a string length stored into current file position of opened
"Shell.ini" file. The argument "fp%" is the file descriptor of opened
"Shell.ini" file. The file pointer must be placed to the byte that the
string length is stored when this function is called.
The file pointer is set to start byte of the string when it finished.
5. Note
5.1. Any functions in this module do not check existence or access permission
of the "Shell.ini" file. They should be checked in the parent procedures
before calling functions in this module.
5.2 Modification on "Shell.ini" takes effect when the system shell restarts.
If you change some preferences of the system shell before restarting the
"Shell.ini" file, all modifications will be lost.
6. Licences
6.1. The copyright of this program and other related products distributed
together (source codes, documents, etc.) belongs to the author of this
program.
6.2. This program is distributed as freeware by the copyrighter. There needs
no payment to use it whichever for commercial or noncommercial.
6.3. The author of this program accepts no claims for physical, mental,
material, monetary, social, religious, political or any kind of damages
brought on you through using this program. Anyone who use this program
must abandon its claims for all damages described above.
6.4. Anyone who got this program can reuse a whole or part of its soure code
for own products and can redistribute them whichever for commercial or
noncommercial without permission of the copyrighter.
6.5. Anyone who makes own products by reusing source code of this program
must not prevent the other people from any rights about this program:
free distribution, free use, free redistribution and free reuse.
6.6. It regards that you agreed to all articles listed above in this chapter
when you use this program or reuse source code of it.
7. Changes history
Ver.1.00 (1 Jun 2002):
- Release.
Ver.1.10 (6 Jul 2003):
- Added checking feature to some functions that verifies whether it seeked
correctly to the silkscreen icon information. As a result, there became
spec changes on some functions.
- Fixed a bug that it cannot seek to silkscreen icon informations if there
was no changes in preferences after hard reset.
- Corrected explanations about file format of "Shell.ini" on this document.
Ver.1.11 (12 Sep 2003):
- Fixed a bug that it cannot seek to silkscreen icon informations if the
"Web" application was not installed in Series 5mx.
Ver.1.12 (25 Oct 2004):
- Added "PSiGetAppCaptionFromFile$:" function.
- Added "PSiReadPosNo&:" function.
- Added "PSiSeekHeadOfAppDat&:" function.
- Rewrited a headder file.
- Modified a default procedure "PSiShowInfo:" as a sample program.
- Modified some other functions.
- Corrected explanations about functions on this document.
ShIniOp