File upload

Fileupload uses the storageApiUrl which can be retrieved from any FileserverInfo.
An optional parameter is the Url parameter.
Normally the XML with the Status and Message will be returned, however when the Url parameter is appended, we will use that to redirect to after uploading finishes.

'Chunking' can, and should be used when uploading large files. The file is then split up in chunks, and uploaded with various calls.

Note that the name of the uploaded file must be one that is supported on all platforms

Authentication Methods

• With a username and password

EXAMPLES

The files must be posted with the name ‘file[]’ to the storageApiUrl.

When using chunking, the Content-Range header must be used in the following format:
"Content-Range: bytes STARTBYTE/ENDBYTE-TOTALBYTES"

Example:
Uploading a file with a size of 150000 bytes and chunk size 100000 bytes requires 2 uploads.

Upload 1:
    "Content-Range: bytes 0/99999-150000"
Upload 2:
    "Content-Range: bytes 100000/149999-150000"

Without the Optional Url parameter:

curl 'https://storage.example.com/storage/api.php?Token=rc1d3ntb53tt6b2vhail6rdtrsxov3v&Task=FileUpload&FileserverName=nmsa000010&Path=/dir/'

With the Url parameter:

curl 'https://storage.example.com/storage/api.php?Token=rc1d3ntb53tt6b2vhail6rdtrsxov3v&Task=FileUpload&FileserverName=nmsa000010&Path=/dir%2F/yes%2F&Url=https://mynomadesk.com/file/finishedupload'

RESPONSE

Without the optional Url parameter:

<Response>
    <Status>999</Status>
    <Message></Message>
    <Files>
        <File>
            <Path>/testfile/file.txt</Path>
            <Status>1</Status>
            <Message</Message>
        </File>
        <File>
            <Path>/testfile/.hiddenfile</Path>
            <Status>4029</Status>
            <Message></Message>
        </File>
    </Files>
</Response>

When all files are uploaded successfully the normal XML is returned:

<Response>
    <Status>1</Status>
    <Message></Message>
</Response>

With the Url parameter a redirect occurs with the Status Code and Message appended, and the FilePath, FileStatus and FileMessage of each file.

curl -g 'https://storage.example.com/mynomadesk/file/finishedupload&Status=999&Message=&FilePath[]=%2Ftestfile%2Ffile.txt&FileStatus[]=4029&FileMessage[]='

Example PHP code that demonstrates a chunked upload

/**
 * Fill in your settings here
 */
$ctrller = "https://storage.example.com/ctrller/api.php";
$email = "email@example.com";
$pw = "password";
$vault_name = 'vaultname'; // -- nmsa name
$chunksize = 100000; // 100kb - Chunk size is in bytes
$filepath = "/path/to/file";

/**
 * First log on so we have an authentication token
 */
$token = Logon($ctrller, $email, $pw);

/**
 * Now we need to know the url for the storage node our vault is located on
 */
$storageapiurl = GetStorageApiUrl($ctrller, $token, $vault_name);

/**
 * Start uploading the file
 */
$result = UploadFile($storageapiurl, $token, $vault_name, $filepath, $chunksize);
$xml = new SimpleXMLElement($result);
echo "Uploaded File -> ".$xml->Message->__toString()."<br /><br /><br />\n\n\n";

/**
 * Log off (invalidates our authentication token)
 */
LogOut($ctrller, $token);


function UploadFile($pUrl, $pToken, $pVaultName, $pFile, $pChunkSize) {
    $upload = function($pFile, $pUrl, $pToken, $pVaultName, $pChunk, $pChunkSize) {
        //Create the temp file for this chunk
        $start = $pChunk * $pChunkSize; // start byte
        $tmp = '/tmp/'.uniqid();
        file_put_contents($tmp, file_get_contents($pFile, false, null, $start, $pChunkSize));
        $end = $start + (filesize($tmp) - 1); // index starts on 0, so end is filesize - 1


        $curl = curl_init();
        $optionsSuccess = true;
        $optionsSuccess &= curl_setopt($curl, CURLOPT_URL, $pUrl);
        $optionsSuccess &= curl_setopt($curl, CURLOPT_SAFE_UPLOAD, false);
        $optionsSuccess &= curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true);
        $optionsSuccess &= curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
        $optionsSuccess &= curl_setopt($curl, CURLOPT_POST, 1);
        $optionsSuccess &= curl_setopt($curl, CURLOPT_HTTPHEADER, [ 'Content-Range: bytes '.$start.'-'.$end.'/'.filesize($pFile) ]);
        $optionsSuccess &= curl_setopt($curl, CURLOPT_POSTFIELDS, [
            'Token' => $pToken,
            'FileserverName' => $pVaultName,
            'Path' => '/',
            'Task' => 'FileUpload',
            'Name' => basename($pFile),
            'file[0]' => new CURLFile($tmp, null, basename($pFile))
        ]);

        $result = curl_exec($curl);
        curl_close($curl);
        unlink($tmp);
        return $result;
    };

    //Start the upload for x chunks
    $size = filesize($pFile);
    $chunks = ($size > $pChunkSize) ? ceil($size / $pChunkSize) : 1;

    echo "Uploading $chunks Chunks <br />\n";
    for($i = 0; $i < $chunks; $i++) {
        echo "Uploading Chunk $i<br />\n";
        $result = $upload($pFile, $pUrl, $pToken, $pVaultName, $i, $pChunkSize);
    }
     return $result;
}

function Logon($pApiUrl, $pEmail, $pPassword) {
    $loginurl = $pApiUrl."?Task=Logon&Email=".$pEmail."&Password=".$pPassword;
    echo "URL -> ".$loginurl."<br />\n";
    $xml = new SimpleXMLElement($loginurl, null, true);
    echo "Logon -> ".$xml->Message->__toString()."<br />\n";

    $securitytoken = $xml->Token->__toString();
    echo "Token -> ".$securitytoken."<br /><br />\n\n";
    return $securitytoken;
}

function LogOut($pApiUrl, $pToken) {
    $logouturl = $pApiUrl."?Task=Logout&Token=".$pToken;
    $xml = new SimpleXMLElement($logouturl, null, true);
    echo "Logout -> ".$xml->Message->__toString()."<br />\n";
}

function GetStorageApiUrl($pApiUrl, $pToken, $pVaultName) {
    $getinfourl = $pApiUrl."?Token=".$pToken."&Task=GetFileserverInfo&FileserverName=".$pVaultName."&ExtendedInfo=false";
    echo "URL -> ".$getinfourl."<br />\n";
    $xml = new SimpleXMLElement($getinfourl, null, true);
    echo "Get FileServerInfo -> ".$xml->Message->__toString()."<br />\n";
    $fileserverName  = $xml->Fileservers->Fileserver->Name->__toString();
    $StorageApiUrl  = $xml->Fileservers->Fileserver->StorageApiUrl->__toString();
    echo "Fileserver Name ->".$fileserverName."<br /><br />\n\n";
    echo "StorageApiUrl ->".$StorageApiUrl."<br /><br />\n\n";
    return $StorageApiUrl;
}