diff options
Diffstat (limited to 'doc/API.txt')
| -rw-r--r-- | doc/API.txt | 216 |
1 files changed, 0 insertions, 216 deletions
diff --git a/doc/API.txt b/doc/API.txt deleted file mode 100644 index 8ccf254..0000000 --- a/doc/API.txt +++ /dev/null @@ -1,216 +0,0 @@ -============================================================================== - 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 |