Storing and Retrieving binary data
Hi Christian, I'm still working on my libBasexCpp and have run into a problem. In my test program, I'm using the following code to test the library's functionality:
std::string input =
“https://upload.wikimedia.org/wikipedia/commons/8/80/BaseX-logo-small-transparent.png”;
cout << “Store a digital object: Session.PutBinary(\”Download_Logo\“,
input);” << endl;
db_PutBin = Session.PutBinary(“Download_Logo”, input);
ReportLib(db_PutBin);
cout << “Retrieve the stored object: Session.Command(\”Binary get
Download_Logo\“)” << endl;
db_GetBin = Session.Command(“binary get Download_Logo”);
ReportLib(db_GetBin);
auto BinObj = db_GetBin -> getBinObject();
std::string OutFile = “/home/bengbers/libBasexTest_Out/BaseX_logo.png”;
cout << OutFile << endl;
saveToFile(BinObj, OutFile);Retrieving binary resources from the database is the only feature of the server protocol that I can’t get to work properly. Here is the librarycode for saving the PNG:
ResultsObject_Uptr BasexClient::PutBinary(const std::string & path,
const std::string & ContentString) { // @suppress(“Name convention for
function”)
ByteVect exec, result; // @suppress(“Multiple variable declaration”)
if (path.empty() || ContentString.empty()) perror(“Path and input
cannot be empty”);
exec = {HEX_PUTBIN};
addVoid(path, exec);
addRawInput(ContentString, exec);
std::cout << “exec # bytes before handshake: ” << exec.size() <<
std::endl;
handShake(exec, result);
std::cout << “exec # bytes after handshake:” << exec.size() <<
std::endl;
std::cout << “result # bytes:” << result.size() << std::endl;
return std::make_unique<ResultsObject>(MethodName::PutBinary, result);The test program gives the following output: Store a digital object: Session.PutBinary(“Download_Logo”, input); Downloaded # bytes: 6753 exec # bytes before handshake: 6769 exec # bytes after handshake: 6769 result # bytes: 29 db_Result -> getStatusString() Status: Success db_Result -> getResultString() No Result available db_Result -> getInfoString() Query executed in 0.42 ms.
Retrieve the stored object: Session.Command(“Binary get Download_Logo”) str.size(): 4030 30 00 00 51 75 65 72 79 20 65 78 65 63 75 74 65 64 20 69 6E 20 30 2E 30 39 20 6D 73 2E 0A 00 00 31 0 0 00 32 00 00 00 53 .. ..
In the debugger, I see that 4,030 bytes are being retrieved from the database. The fact that my code only outputs 30 00 00 in this case does match the retrieved data. I know that in binary data, 0xFF and 0x00 are encoded with an extra 0xFF. When the binary data is retrieved, the extra 0xFF is removed. My question is: does the BaseX server automatically encode this data when saving binary data? Or do I need to handle the encoding myself?
Or do you have another explanation for why retrieving the binary data isn’t working?
Ben
Hi Ben,
The server doesn’t escape your input – the escaping rule applies in both directions. Before sending PUTBINARY input, prefix every \00 and \FF byte with \FF; the server removes the prefixes again.
Currently, the \00 at byte 9 of the PNG (89 50 4E 47 0D 0A 1A 0A 00 …) ends the input: only 8 bytes are stored, and the remaining bytes are interpreted as new commands. This is why you get unrelated responses (“Query executed…”, query ids) and everything is out of sync. Once fixed, BINARY GET should return 89 50 4E 47 ….
Please also note that BaseX 13.0 replaces digest authentication with a salted SHA-256 handshake, so libBasexCpp will need an update to connect to the latest version. Details:
* https://docs.basex.org/main/Clients (Writing a New Binding) * https://docs.basex.org/main/Server_Protocol (Conventions, Authentication)
Best, Christian
Quoted text · Engbers · 70 lines
Ben Engbers@dds via BaseX-Talk <basex-talk at mailman.uni-konstanz.de> schrieb am Donnerstag, 19. November 2026 um 20:14: > Hi Christian, > I'm still working on my libBasexCpp and have run into a problem. In my > test program, I'm using the following code to test the library's > functionality: > > std::string input = > “https://upload.wikimedia.org/wikipedia/commons/8/80/BaseX-logo-small-transparent.png”; > cout << “Store a digital object: Session.PutBinary(\”Download_Logo\“, > input);” << endl; > db_PutBin = Session.PutBinary(“Download_Logo”, input); > ReportLib(db_PutBin); > cout << “Retrieve the stored object: Session.Command(\”Binary get > Download_Logo\“)” << endl; > db_GetBin = Session.Command(“binary get Download_Logo”); > ReportLib(db_GetBin); > auto BinObj = db_GetBin -> getBinObject(); > std::string OutFile = “/home/bengbers/libBasexTest_Out/BaseX_logo.png”; > cout << OutFile << endl; > saveToFile(BinObj, OutFile); > > Retrieving binary resources from the database is the only feature of the > server protocol that I can’t get to work properly. > Here is the librarycode for saving the PNG: > ResultsObject_Uptr BasexClient::PutBinary(const std::string & path, > const std::string & ContentString) { // @suppress(“Name convention for > function”) > ByteVect exec, result; // @suppress(“Multiple variable declaration”) > if (path.empty() || ContentString.empty()) perror(“Path and input > cannot be empty”); > exec = {HEX_PUTBIN}; > addVoid(path, exec); > addRawInput(ContentString, exec); > std::cout << “exec # bytes before handshake: ” << exec.size() << > std::endl; > handShake(exec, result); > std::cout << “exec # bytes after handshake:” << exec.size() << > std::endl; > std::cout << “result # bytes:” << result.size() << std::endl; > return std::make_unique<ResultsObject>(MethodName::PutBinary, result); > > The test program gives the following output: > Store a digital object: Session.PutBinary(“Download_Logo”, input); > Downloaded # bytes: 6753 > exec # bytes before handshake: 6769 > exec # bytes after handshake: 6769 > result # bytes: 29 > db_Result -> getStatusString() Status: Success > db_Result -> getResultString() No Result available > db_Result -> getInfoString() Query executed in 0.42 ms. > > Retrieve the stored object: Session.Command(“Binary get Download_Logo”) > str.size(): 4030 > 30 00 00 51 75 65 72 79 20 65 > 78 65 63 75 74 65 64 20 69 6E > 20 30 2E 30 39 20 6D 73 2E 0A 00 00 31 0 0 00 32 00 00 00 53 .. .. > > In the debugger, I see that 4,030 bytes are being retrieved from the > database. The fact that my code only outputs 30 00 00 in this case does > match the retrieved data. > I know that in binary data, 0xFF and 0x00 are encoded with an extra > 0xFF. When the binary data is retrieved, the extra 0xFF is removed. > My question is: does the BaseX server automatically encode this data > when saving binary data? Or do I need to handle the encoding myself? > > Or do you have another explanation for why retrieving the binary data > isn’t working? > > Ben >
Written for BaseX 13.0, the current version.