From 52caed76bb0b83f7c89d858a4c2f5a933462bae2 Mon Sep 17 00:00:00 2001 From: Lubos Lunak Date: Fri, 3 Mar 2006 16:42:42 +0000 Subject: Add a conventions section instead of repeating the same all the time. --- doc/API.txt | 63 +++++++++++++++++++++++++++++++++++++------------------------ 1 file changed, 38 insertions(+), 25 deletions(-) diff --git a/doc/API.txt b/doc/API.txt index 79d5df0..c3e4c22 100644 --- a/doc/API.txt +++ b/doc/API.txt @@ -1,30 +1,43 @@ +Conventions: +============ + +All strings, filenames, urls, etc. are UTF8-encoded, unless specified +otherwise. + +All filenames and paths must be absolute. + + +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 OpenUrl( string url ) -> ( bool ok ) -==================================== +------------------------------------ -Opens the given URL in the default web browser. +Opens the given URL or filename in the default web browser. -url: UTF8-encoded url to open +url: URL or filename to open ok: if false, the url wasn't opened ExecuteUrl( string url ) -> ( bool ok ) -======================================= +--------------------------------------- -Opens the given url in the default application for the file (image viewer for image, etc.) +Opens the given URL or filename in the default application for the file (image viewer for image, etc.) -url: UTF8-encoded url to open -ok: if false, the file wasn't opened +url: URL or filename to open +ok: if false, the URL/file wasn't opened ButtonOrder() -> ( int order ) -============================== +------------------------------ Returns the system button order. @@ -34,17 +47,17 @@ order: 0 - error RunAsUser( string user, string command ) -> ( bool ok ) -======================================================= +------------------------------------------------------- Executes the given command as a different user. -user: username as UTF8-encoded string or empty for superuser -command: UTF8-encoded command to execute +user: username or empty for superuser +command: command to execute ok: if false, the command wasn't executed SuspendScreensaving( bool suspend ) -> ( bool ok ) -================================================== +-------------------------------------------------- Suspends or resumes screensaving. @@ -53,7 +66,7 @@ ok: if false, suspending failed MailTo( string subject, string body, string to, string cc, string bcc, stringlist attachments ) -> ( bool ok ) -=============================================================================================== +-------------------------------------------------------------------------------------------------------------- Opens a window for composing mail in the default mail client. @@ -62,46 +75,46 @@ 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 UTF8-encoded files to be attached to the mail +attachments: a list of filenames to be attached to the mail LocalFile( string url, string local, bool allow_download ) -> ( string result ) -================================================================= +------------------------------------------------------------------------------- -Converts a file URL to a local file location, downloading the remote file +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: UTF8-encoded URL or path of the file to convert to local file +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: UTF8-encoded filename of a local file that should be used as a temporary file +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 -result: UTF8-encoded filename of the resulting local file, may be equal to the source file +result: filename of the resulting local file, may be equal to the source file UploadFile( string local, string file, bool remove_local ) -> ( 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: UTF8-encoded filename of a temporary file obtained from LocalFile -file: UTF8-encoded URL or path of the location where to save the file to +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 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: UTF8-encoded filename of a temporary file to be removed +local: filename of a temporary file to be removed ok: if false, the removal failed -- cgit v1.2.3