1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
|
==============================================================================
Description of the API
==============================================================================
This file is a complete list and description of all API calls. It doesn't
contain any information specific to any language bindings.
Conventions:
============
All strings, filenames, urls, etc. are UTF8-encoded, unless specified
otherwise.
All filenames and paths must be absolute.
Window relations:
-----------------
Many calls take 'windowinfo' argument that specifies a window related to the call.
This argument is necessary for maintaining proper window relations so that e.g.
a dialog opened from the call is properly associated with a window from the application
to which it logically belongs. Missing or incorrect data may result in focus problems.
Applications should specify the toplevel window related to the request. If the application
has only one main window then this is the window, if it has more then the relevant
one should be used (e.g. for the OpenUrl call the window should be the toplevel window
in which the user clicked on the link). See bindings documentation for further details.
API calls list:
===============
Init() -> ( bool ok )
---------------------
Needs to be the very first call performed. If the call fails, no API can be used.
ok: if false, initialization failed
Capabilities() -> ( int[] capabilities )
----------------------------------------
Returns a list of all commands that the desktop supports. Refer to your
bindings documentation for details on command id's.
capabilities: a list of capabilities
OpenUrl( string url, windowinfo winfo ) -> ( bool ok )
------------------------------------------------------
Opens the given URL or filename in the default web browser.
url: URL or filename to open
winfo: window related to this request (see conventions)
ok: if false, the url wasn't opened
ExecuteUrl( string url, windowinfo winfo ) -> ( bool ok )
---------------------------------------------------------
Opens the given URL or filename in the default application for the file (image viewer for image, etc.)
url: URL or filename to open
winfo: window related to this request (see conventions)
ok: if false, the URL/file wasn't opened
ButtonOrder() -> ( int order )
------------------------------
Returns the system button order.
order: 0 - error
1 - Ok/Cancel
2 - Cancel/Ok
RunAsUser( string user, string command, windowinfo winfo ) -> ( bool ok )
-------------------------------------------------------------------------
Executes the given command as a different user.
user: username or empty for superuser
command: command to execute
winfo: window related to this request (see conventions)
ok: if false, the command wasn't executed
SuspendScreensaving( bool suspend ) -> ( bool ok )
--------------------------------------------------
Suspends or resumes screensaving.
suspend: whether to suspend screensaving
ok: if false, suspending failed
MailTo( string subject, string body, string to, string cc, string bcc, string[] attachments, windowinfo winfo ) -> ( bool ok )
------------------------------------------------------------------------------------------------------------------------------
Opens a window for composing mail in the default mail client.
subject: mail subject or empty
body: mail body or empty
to: mail's To:, multiple entries are separated using commas, may be empty
to: mail's CC:, multiple entries are separated using commas, may be empty
to: mail's BCC:, multiple entries are separated using commas, may be empty
attachments: a list of filenames to be attached to the mail
winfo: window related to this request (see conventions)
LocalFile( string url, string local, bool allow_download, windowinfo winfo ) -> ( string result )
-------------------------------------------------------------------------------------------------
Converts an URL to a local file location, downloading the remote file
if necessary and allowed. The URL may be already a local file in which
case it will be simply returned.
file: URL or path of the file to convert to local file
allow_download: If the file URL doesn't point to a local file, it will be downloaded
to a temporary local file if allow_download is true
local: filename of a local file that should be used as a temporary file
in case of downloading; if empty, then a random temporary file is used and it needs
to be eventually removed using RemoveTemporaryLocalFile; note that if the source
file already is a local file, then its path will be returned and this field will
be ignored
winfo: window related to this request (see conventions)
result: filename of the resulting local file, may be equal to the source file
UploadFile( string local, string file, bool remove_local, windowinfo winfo ) -> ( bool ok )
-------------------------------------------------------------------------------------------
Uploads local file to its URL location. This function is a complement for LocalFile
to save a temporary file to its real location after it's been changed. In case
the destination is a local file then this call successfully returns without doing anything.
local: filename of a temporary file obtained from LocalFile
file: URL or path of the location where to save the file to
remove_local: if true, equivalent to calling RemoveTemporaryLocalFile with the local
file after this call
winfo: window related to this request (see conventions)
ok: if false, the upload failed
RemoveTemporaryLocalFile( string local ) -> ( bool ok )
-------------------------------------------------------
Removes a temporary local file created by LocalFile (only works it LocalFile had
to create a random temporary file itself). This call doesn't affect files that
haven't been created by LocalFile.
local: filename of a temporary file to be removed
ok: if false, the removal failed
AddressBookList() -> ( stringlist contact_ids, bool ok )
----------------------------------------------------------
Lists all identifiers for contacts in the user's addressbook. The content of such
an identifier can vary between daemon implementations.
contact_ids: a list of string IDs, one entry for each contact in the addressbook
ok: false if listing is not possible or has failed
AddressBookOwner() -> ( string contact_id, bool ok )
----------------------------------------------------
Returns the identifier of the user's own contact if available.
contact_id: a string identifying the user herself
ok: true if owner contact is available, otherwise false
AddressBookFindByName( string name ) -> ( stringlist contact_ids, bool ok )
-----------------------------------------------------------------------------
Finds all contacts in the user's addressbook where the given string is part
of at least one of the contact's name fields.
name: a string containing the name or part of a name to search for
contact_ids: a list of string IDs, one entry for each matching contact in
the addressbook
ok: false if no match is found
AddressBookGetName( string contact_id ) -> ( string givenname, string familyname, string fullname, bool ok )
------------------------------------------------------------------------------------------------------------
Gets the name of a specific contact from the user's addressbook.
The contact is identified through a backend specific string which is returned by
query functions such as AddressBookList or AddressBookFindByName.
contact_id: the identifier of the contact to get the name from
givenname: the given or first name of the contact
familyname: the family name of the contact
fullname: a name string containing all avilable name parts, e.g. name plus title
ok: false if the contact_id is unknown
AddressBookGetEmails( string contact_id ) -> ( stringlist emails, bool ok )
-----------------------------------------------------------------------------
Gets all emails for the contact with the given identifier.
contact_id: the identifier of the contact to get the email addresses from
emails: a list of strings, one entry for each email address of the contact
ok: false if the contact_id is unknown
AddressBookGetVCard30( string contact_id ) -> ( string vcard, bool ok)
----------------------------------------------------------------------
Gets the full contact information as a VCard version 3.0.
contact_id: the identifier of the contact to get the vcard for
vcard: a string with the vcard data
ok: true if contact exists and conversion successfull, otherwise false
|
