File Transfer

File transfers are not implemented between controls but between nodes, building on top of ZCom_Node's event system. That means, file transfers will get prioritized by the node's priority and connection specific relevance. Additionally, a file transfer itself has an aggressivenes option which influences how big the sent chunks are. The bigger the chunks, the lower the amount of space left in the current packet for other nodes. When having a low node priority but aggressivenes is 1.0, the file transfer will occupy a whole packet once in a while, whereas a high node priority with a low aggressivenes will transfer small chunks of the file but with a higher frequency.

To start a filetransfer, you will need two nodes connected to each other. The direction of file transfers is not restricted. Let's call the nodes 'snode' for the node on the server and 'cnode' for the client. File transfer basically involves two special methods in ZCom_Node plus handling of some node events.

snode->sendFile("./data/the_file.txt",          // path to file in local filesystem
                "the_file.txt",                 // path the receiver will see
                1,                              // connection ID of destination node
                NULL,                           // meta information can be optionally sent via ZCom_BitStream
                1.0f);                          // aggressivenes

It is not possible to send a file to all nodes at once, so sendFile() needs a target connection id. Cnode will receive the event ZCom_Node::eEvent_File_Incoming eventually.

eZCom_Event       type;            // event type
ZCom_ConnID       conn_id;         // connection id of sender

ZCom_BitStream *data = cnode->getNextEvent(&type, NULL, &conn_id);
if (type == eZCom_EventFile_Incoming && data)
{
  ZCom_FileTransID fid = (ZCom_FileTransID) data->getInt(ZCOM_FTRANS_ID_BITS);
  ZCom_FileTransInfo info = node->getFileInfo(fid);
  if (info.id == ZCom_Invalid_ID) {
    // there was an error
  } else {
    // accept the file
    // NULL as 3rd parameter instructs zoidcom to store it
    // to the location proposed by the sender
    node->acceptFile(conn_id, fid, NULL, true);
  }
}

The attached bitstream returned by getNextEvent() contains as first info, the file transfer ID. Together with the sender's connection ID, the file transfer can be uniquely identified. All other information about this file transfer is stored inside the ZCom_FileTransInfo structure, which can be retrieved at any time as long as the filetransfer is valid. For the sender that means between the call to sendFile() and the receival of either eZCom_EventFile_Aborted or eZCom_EventFile_Complete. For the receiver it means between the receival of eZCom_EventFile_Incoming and aborting it via acceptFile(.., false) or the receival of eZCom_EventFile_Aborted due to an error. If file transfer information is not available, the struct will have ZCom_Invalid_ID in the ID field.

If the sender supplied metadata to the data parameter in sendFile(), this can be extracted from the bitstream after reading the file transfer ID.

To accept or deny a file transfer, ZCom_Node::acceptFile() needs to be called. The first two parameters describe the file transfer in question, the third is a const char *, and if non-NULL, describes where Zoidcom should store the file. If NULL, it will be stored in the supplied location aka ZCom_FileTransInfo::path aka parameter _pathtosend to sendFile().

The last parameter to acceptFile() is a bool, say 'true' to accept or 'false' to deny the transfer. In latter case, eEvent_File_Aborted will be received by the sender. This also happens if the client is unable to open the target file or write to it during transfer.

For each chunk received during transfer, eEvent_File_Data is generated on the client, not containing the received data, but merely serving as progress notification. After transmission of the whole file, eEvent_File_Complete is received on both client and server.

---