File Descriptors, reading & writing data, chunked upload
The file descriptors are an abstract indicator for accessing a file. With these descriptors low level operations are available for the files in pCloud file system - create, read, write , etc.
Accessing descriptors
When you open a file with
file_open you will get a file descriptor. You can use it to read and write data to the file. File descriptors are numbers, the first descriptor is always
1. Instead of using the actual descriptor number, you can refer files by the sequence they were opened in.
You can refer to the last opened file by descriptor
-1, the one opened before that
-2, etc.. That is useful if you want to pipeline open request together with read/write requests without waiting for the answer.
Of course, if the open fails, all subsequent pipelined read/write operations for it will fail too. Failed opens however also waste file descriptors, which is useful because you can pipeline for example three open commands and if the second one fails, still addressing first descriptor by
-3 will still be correct as well as addressing the last one by
-1. Descriptor numbers are not reused.
A descriptor is only valid for the same connection. If a connection closes, all the files are also closed. You can open the same file in multiple connections.
This can be used for chunked upload - open the file and then write chunks with write. If the connection drops, it is safe to resume upload from the current file size (if you of course write data sequentially).
Reading data
When reading data from file, data will be sent to you on the same connection that you requested it. That might be not really convenient if you expect a JSON response. So, when using
file_read and
file_pread you should generally expect binary data.
When you are getting data, the
'Content-Type' will be
'application/octet-stream'. In case of error,
'Content-Type' will be
'application/json' as usual and the
'X-Error: xxxx' header will be present. If you are getting data, observe
'Content-Length' to see how much data you are getting. Normally you will get all the data you requested, except in cases that you want to read more data than is available (past the current file offset).
Writing data
Writing data to file with
file_write/
file_pwrite methods works the same way as with uploading files - you can either use the
PUT method, where the data of with size of
'Content-Length' will be sent after the headers.
Or you can use
POST with
'multipart/form-data' encoding. In this case the data should be send in the field named "data" found after any post parameters (as with uploading files).