Upload/Download plugin

From KuneriLite wiki

Contents

Introduction

KuneriLite Upload/Download plug-in provides an API to upload/download any file from/to any location on local device.

IMPORTANT NOTES

klApId (disables all Internet Access Point dialogs) is not available in the KuneriLite version 0.9.7.1, but will be available in next version. It is available already in commercially licensed KuneriLite Ul/Dl plug-in.

Interface

loadVariables("http://127.0.0.1:<Port>/<Key>/uldl?klCommand=<Command>&<Arguments>,
"<TargetMc>", "<Method>" );
General Parameters
<Port> Specific port KuneriLite is listening commands from (default 1001)
<Key> Unique key for your KuneriLite license (default Basic)
<Command> Name of the command to be called.
<Arguments> Required arguments for commands. Each command may have different arguments with various parameter values.
<TargetMC> Flash Lite movie clip that will receive the response back.
<Method> Use "POST"-method when writing large amount(>800 bytes) of data, otherwise leave this field empty.

Status of a command can be controlled via klError and klEnd variables. klError returns the response message from KuneriLite server application and klEnd value indicates that conversation is finalized and all data is received. For meaning of klError values, please refer to "Error Values" section below

loadVariables-call syntax is different for POST method.

Commands

Download

Downloads a file from a given URL.

Before download is started, access point to use will be asked from user. It won't be asked again; same access point will be used until exit command is called.

If application is closed before downloading is over, downloading will still proceed and plug-in will be deleted from memory after downloading is ended.

Returns

Returns 0 to klError if successful, or an error code if there is any problem with download.

Arguments

klTrId Unique transaction identifier of a download in decimal format. Will be removed automatically as a download is completed.
klUrl URL of the remote file to download
klFile Destination of the file to save on device. If folder of file is not given, file is stored into application installation folder. Relative paths are also supported.
klApId Access point id (returned by previous "status" command), to disable first-time Access Point question -dialog.

Example

loadVariables("http://127.0.0.1:1001/Basic/uldl?klCommand=download&klTrId=1234&
klUrl=http://www.kunerilite.net/media/KLDownloadTest.swf&klFile=KLDownloadTest.swf", "" );

Upload

Uploads a file to a given URL. Before upload is started, access point to use will be asked from user. It won't be asked again; same access point will be used until exit command is called.

If application is closed before uploading is over, uploading will still proceed and plug-in will be deleted from memory after transaction is ended.

Returns

Returns 0 to klError if successful, or an error code if there is any problem with upload.

Arguments

klTrId Unique transaction identifier of a transfer. Will be removed automatically as a transfer is completed.
klUrl URL of the server side script
klFile Source of the file to upload to server. If folder of file is not given, file is looked from application installation folder. Relative paths are also supported, withing application install folder(must be subfolder).
klType MIME type of the file. __Must__ be specified. Please see MIME type list for more detailed information.
klApId Access point id (returned by previous "status" command), to disable first-time Access Point question -dialog.

Example

loadVariables("http://127.0.0.1:1001/Basic/uldl?klCommand=upload&klTrId=1234&klUrl=http://username:password@www.example.com/test/get.php&klFile=image.jpeg&klType=image/jpeg", "" );

Server side script

KuneriLite passes file as HTTP multipart/form-data to server. Therefore some server side scripting implementation is needed.

KuneriLite defines form-data as following: Content-Disposition: form-data; name="klFileUpload"; filename="<file>" and same names should be used in scripts (see example below).

This is an example of get.php which can be used in server:

<?php

// In this example a directory "images" needs to be present on the same directory where
// get.php is, with the necessary rights for the script to write data inside

// Full path of the images folder to upload images to
$content_dir = '/home/example/public_html/test/images/';
$filename = Null;

if(isset($_POST['fileName'])){
    $filename = $_POST['fileName'];
}

if(isset($_FILES['klFileUpload'])){
    if ($filename == Null){
        $filename = $_FILES['klFileUpload']['name'];
    }

    if( !move_uploaded_file($_FILES['klFileUpload']['tmp_name'],$content_dir . $filename) ){
        exit("Couldn't write the file in $content_dir");
    }
} else {
    // something when wrong
    exit("False");
}

// return
echo "True";

?>

LoadVariables

Loads variables from the given URL (also sending is possible by embedding the variables in the URL, see the example).
Advantage over Flash Lite loadVariables command is that Access Point is prompted only once.

Returns

Returns 0 to klError if successful, or an error code if there is any problem in loading.

If transfer was successful, returns also new loaded variables into target movieclip.

Arguments

klUrl URL to pass. All required variables to send must be included in URL.
klApId Access point id (returned by previous "status" command), to disable first-time Access Point question -dialog.

Note!

klUrl value must be escape-encoded Url-format!

loadVariables -command does not send other variables in the stage when POST -method is used, only variables embedded in the klURL are possible to be sent.

Example

This sends string variable%201=value to the server.
(klUrlDecodeOff=1 disables default URL-decoding in KuneriLite for this request, so that %20 won't turn into space (' ') charater)

loadVariables("http://127.0.0.1:1001/Basic/uldl?klCommand=loadVariables&
klUrl=http://www.example.com/page/get.php?variable%201=value&klUrlDecodeOff=1",
"" );

Status

Gives information about the status of a download or upload in progress. This command in important for to catch the time when transfer is successfully completed (klStatus=complete).

In case of download; when it is successful, the downloaded file is unlocked and available to use.

Returns

Returns 0 to klError if successful, or an error code if there is any problem retrieving the status.

When Status command is called, it returns the result to 2 variables; klStatus and klProgress
Note: klProgress returns progress value only for 'download' command.

klStatus Status of the connection. Can be disconnected, connecting, connected, loading, complete and failed.
klProgress Progress of the download between 0-100. Is not supported for upload.
klApId Access point id used in the transmission. Id can be used in all further (load) commands to disable Access Point question -dialogs. Using this it is possible to initiate all down-/uploads/loadVariable commands in the background, silently.

A sample response from KuneriLite server can be seen below;

klError=0&klStatus=disconnected&klProgress=0&klEnd=1&

Arguments

klTrId Unique identifier of the download/upload in progress.

Example

loadVariables("http://127.0.0.1:1001/Basic/uldl?klCommand=status&klTrId=1234", "");

Stop

Stops the download or upload with given transaction id.

Returns

Returns 0 to klError if successful, or an error code if there is any problem stopping.

Arguments

klTrId Unique transaction identifier of the download or upload in progress. Will be removed automatically as a transaction is stopped.

Example

loadVariables("http://127.0.0.1:1001/Basic/uldl?klCommand=stop&klTrId=1234", "" );

createAP

This command is not available in KuneriLite public version, since it makes whole Ul/Dl plugin to require signing, which is not convenient for testing.
It is available as custom plug-in from Kuneri.

With this command any kind of access point can be created. Access point type, names, addresses, proxy settings etc. can be defined. Returns access point ID variable back and it can be used in further upload/download commands.

Resize

Sometimes image about to be uploaded or after downloading requires up-/downscaling. Resize command simply resizes JPEG-image to given in width*height dimensions.

Returns

Returns 0 to klError if successful, or an error code if there is any problem in resizing.
If klTargetFile variable wasn't given, it will be generated and returned back in form klTargetFile=[klFile][hash] (for example myfilebg8d13.jpg).

Arguments

klFile Path to source image
klTargetFile Target image path.

If target file is not given, target file will be random name in form [klFile][hash].jpg, (name will be returned back in klTargetFile variable).

klSize New image dimensions in pixels
klOverwrite Overwrites existing file, on by default.

Example

loadVariables("http://127.0.0.1:1001/Basic/uldl?klCommand=resize&
klFile=test.jpg&klSize=200*320&klTargetFile=test_thumb.jpg&klOverwrite=false",
"");

Exit

Closes all transactions. Recommended to call before exiting the application, if there is no need to preserve ongoing downloads/uploads.

Returns

Returns 0 to klError if successful, or an error code if there is any problem exiting.

Arguments

None.

Example

loadVariables("http://127.0.0.1:1001/Basic/uldl?klCommand=exit", "");

Error values

Common error statuses are mentioned below.

0 Success
-1 File to upload/download is not found, transaction ID is not found or some KuneriLite components are missing
-3 User pressed 'Cancel' in IAP dialog or there is no available connections. Possible only to 'status' command.
-4 File to upload is too big (limit depends of available memory).
-5 Plugin name, command or type in URL is not supported / restricted command
-6 Given arguments are invalid
-11 Transaction ID already exists and transaction is active
-12 Given target path for download or upload is not found
-18 System is not yet ready for new upload/download. Re-issue the request in this case.
-28 Given URL is malformed
-36 Connection was disconnected for some reason

System HTTP errors

System error codes are in range -7200 to -7399.
Most common codes are:

-7331 Content body is missing (length is 0)
-7373 Given URL is invalid

Some system HTTP errors are given in form -51xx.

-5120 No response from DNS server (timeout).
Personal tools