From d596a09c3f7ad505bdb272d8486b6d6b6c74e6bd Mon Sep 17 00:00:00 2001 From: Natalia Date: Tue, 30 Aug 2022 17:33:55 +0300 Subject: [PATCH] updated the c++ builder wrapper api --- DesktopEditor/doctrenderer/docbuilder.h | 209 ++++++++++++++---------- 1 file changed, 122 insertions(+), 87 deletions(-) diff --git a/DesktopEditor/doctrenderer/docbuilder.h b/DesktopEditor/doctrenderer/docbuilder.h index 71b6c7003a..0bd67b7fe5 100644 --- a/DesktopEditor/doctrenderer/docbuilder.h +++ b/DesktopEditor/doctrenderer/docbuilder.h @@ -57,8 +57,8 @@ namespace NSDoctRenderer }; /** - * Class for getting the results of called js commands. - * It represents a wrapper for a js object. + * Class for getting the results of called JS commands. + * It represents a wrapper for a JS object. */ class CDocBuilderValue_Private; class Q_DECL_EXPORT CDocBuilderValue @@ -146,6 +146,7 @@ namespace NSDoctRenderer /** * Returns a property of this object. + * @param name The name of the CDocBuilderValue object property. */ CDocBuilderValue GetProperty(const wchar_t* name); @@ -159,15 +160,24 @@ namespace NSDoctRenderer /** * Returns an array value by its index. + * @param index The index of the array value. */ CDocBuilderValue Get(const int& index); CDocBuilderValue operator[](const int& index); /** * Sets a property to this object. + * @param name The name of the CDocBuilderValue object property. + * @param value The value of the CDocBuilderValue object property. */ void SetProperty(const wchar_t* name, CDocBuilderValue value); void Set(const wchar_t* name, CDocBuilderValue value); + + /** + * Sets an array value by its index. + * @param index The index of the array value. + * @param value The array value to be set. + */ void Set(const int& index, CDocBuilderValue value); public: @@ -181,18 +191,25 @@ namespace NSDoctRenderer /** * Please use CDocBuilderContext::CreateUndefined - * This method returns the current context and calls its method. + * Creates an undefined value. This method returns the current context and calls its CreateUndefined method. */ static CDocBuilderValue CreateUndefined(); /** * Please use CDocBuilderContext::CreateNull - * This method returns the current context and calls its method. + * Creates a null value. This method returns the current context and calls its CreateNull method. */ static CDocBuilderValue CreateNull(); public: /** - * The object methods for calling functions that make writing code easier. + * Calls the specified Document Builder method. + * @param name The name of the Document Builder method in the Unicode or UTF8 format. + * @param p1 The first parameter that the Document Builder method takes as an argument. + * @param p2 The second parameter that the Document Builder method takes as an argument. + * @param p3 The third parameter that the Document Builder method takes as an argument. + * @param p4 The fourth parameter that the Document Builder method takes as an argument. + * @param p5 The fifth parameter that the Document Builder method takes as an argument. + * @param p6 The sixth parameter that the Document Builder method takes as an argument. */ CDocBuilderValue Call(const char* name); CDocBuilderValue Call(const char* name, CDocBuilderValue p1); @@ -217,7 +234,7 @@ namespace NSDoctRenderer }; /** - * Stack-allocated class which sets the execution context for all operations executed within a local scope. + * The stack-allocated class which sets the execution context for all operations executed within a local scope. * All opened scopes will be closed automatically when the builder CloseFile method is called. */ class CDocBuilderContextScope_Private; @@ -241,7 +258,7 @@ namespace NSDoctRenderer }; /** - * Class for getting js context for working. + * Class for getting JS context for working. */ class CDocBuilderContext_Private; class Q_DECL_EXPORT CDocBuilderContext @@ -252,49 +269,56 @@ namespace NSDoctRenderer CDocBuilderContext& operator=(const CDocBuilderContext& src); ~CDocBuilderContext(); - /* - * Creates an undefined value, an analogue of undefined in js. + /** + * Creates an undefined value, an analogue of undefined in JS. */ CDocBuilderValue CreateUndefined(); - /* - * Creates a null value, an analogue of null in js. + /** + * Creates a null value, an analogue of null in JS. */ CDocBuilderValue CreateNull(); - /* - * Creates an empty object, an analogue of {} in js. + /** + * Creates an empty object, an analogue of {} in JS. */ CDocBuilderValue CreateObject(); - /* - * Creates an array value, an analogue of new Array(length) in js. + /** + * Creates an array value, an analogue of new Array (length) in JS. + * @param length The array length. */ CDocBuilderValue CreateArray(const int& length); - /* - * Creates a Uint8Array value, an analogue of Uint8Array in js. If externalize == true, the application needs to release the memory after freeing the Uint8Array. - * Otherwise, the memory will be released automatically. In this case, the buffer must be created with the AllocMemoryTypedArray method. + /** + * Creates a Uint8Array value, an analogue of Uint8Array in JS. + * @param buffer The array buffer. + * @param length The array length. + * @param externalize Specifies if the application releases the memory after freeing Uint8Array (true). + * If this parameter is false, then the memory will be released automatically. In this case, the buffer must be created with the AllocMemoryTypedArray method. */ CDocBuilderValue CreateTypedArray(unsigned char* buffer, const int& length, const bool& externalize); - /* - * Method to allocate the memory for a typed array. + /** + * Allocates the memory for a typed array by creating a buffer array of the specified size. + * @param size The buffer array size. */ static unsigned char* AllocMemoryTypedArray(const size_t& size); - /* - * Method to free the memory for a typed array. + /** + * Frees the memory for a typed array. + * @param data The allocated memory to be released. + * @param size The buffer array size. */ static void FreeMemoryTypedArray(unsigned char* data, const size_t& size); - /* - * Returns the global object for the context. + /** + * Returns the global object for the current context. */ CDocBuilderValue GetGlobal(); - /* - * Creates a context scope. + /** + * Creates a context scope which sets the execution context for all operations executed within a local scope. */ CDocBuilderContextScope CreateScope(); - /* - * Checks for errors in js. The error message and call stack will be written to std::cerr. + /** + * Checks for errors in JS. The error message and call stack will be written to std::cerr. */ bool IsError(); @@ -306,7 +330,7 @@ namespace NSDoctRenderer }; /** - * Base class used by ONLYOFFICE Document Builder for the document file (text document, spreadsheet, PDF) to be generated. + * Base class used by ONLYOFFICE Document Builder for the document file (text document, spreadsheet, presentation, form document, PDF) to be generated. */ class CDocBuilder_Private; class Q_DECL_EXPORT CDocBuilder @@ -319,7 +343,7 @@ namespace NSDoctRenderer /** * Opens the document file which will be edited and saved afterwards. * @param path The path to the file to be opened together with its name and extension. - * @param params The parameters needed for the correct file opening (most commonly the encoding is used for the txt and csv file types or the delimiter for the csv files, + * @param params The parameters needed for the correct file opening (most commonly, the encoding is used for the txt and csv file types or the delimiter for the csv files, * for other file types this is just an empty string). The parameters are added in the form of XML tags, where m_nCsvTxtEncoding is used for the text encoding * and m_nCsvDelimiter is used for the csv delimiter. The supported values for the csv delimiters include: 0 - no delimiter; 1 - tab; 2 - semicolon; 3 - colon; 4 - comma; 5 - space. * @return Process x2t return code @@ -327,7 +351,7 @@ namespace NSDoctRenderer int OpenFile(const wchar_t* path, const wchar_t* params); /** * Creates a new file. The type of the file which will be created needs to be set. - * @param type The type of the file to be created is specified as a hexadecimal integer for the C++ code or docx, xlsx or pptx for the .docbuilder script file (see AVS_OFFICESTUDIO_FILE_XXX values). + * @param type The type of the file to be created set as a hexadecimal integer for the C++ code or docx, xlsx or pptx for the .docbuilder script file (see AVS_OFFICESTUDIO_FILE_XXX values). * @return True if the operation is successful */ bool CreateFile(const int& type); @@ -339,13 +363,20 @@ namespace NSDoctRenderer void SetTmpFolder(const wchar_t* folder); /** * Saves the file after all the changes are made. The type of the file which will be saved needs to be set. - * @param type The type of the file to be saved is specified as a hexadecimal integer for the C++ code; for the .docbuilder script file the following values are possible: + * @param type The type of the file to be saved is set as a hexadecimal integer for the C++ code. For the .docbuilder script file the following values are possible: * docx, odt, rtf, txt, pptx, xlsx, ods, csv, pdf (see AVS_OFFICESTUDIO_FILE_XXX values). * @param path The path to the file to be saved together with its name and extension. - * @param params The parameters needed for the correct file opening (most commonly the encoding is used for the txt and csv file types or the delimiter for the csv files, + * @param params The parameters needed for the correct file saving (most commonly, the encoding is used for the txt and csv file types or the delimiter for the csv files, * for other file types this is just an empty string). The parameters are added in the form of XML tags, where m_nCsvTxtEncoding is used for the text encoding * and m_nCsvDelimiter is used for the csv delimiter. The supported values for the csv delimiters include: 0 - no delimiter; 1 - tab; 2 - semicolon; 3 - colon; 4 - comma; 5 - space. - * When saving into an image file (png or jpg) for creating thumbnails, the additional parameters are used. + * When saving into an image file (png or jpg) for creating thumbnails, the additional parameters in the form of XML tags are used: + * * m_oThumbnail - the core tag showing that the inner nodes will be used to create a thumbnail out of the document file; + * * format - the image file format used to create a thumbnail (can be of the following values: 3 - for a JPG file, 4 - for a PNG file); + * * aspect - the image aspect when creating a thumbnail from the document file (can be of the following values: 1 - will keep the original aspect, 0 - will stretch the image to fit the width and the height set below; + * * first - whether only the first page or all the pages should be converted into a thumbnail (can be of the following values: true - only the first page will be converted, false - all the document pages will be used to create thumbnails, in this case the file will be saved as an archive of images, one for each page); + * * width - the image width in pixels; + * * height - the image height in pixels. + * For example: oBuilder.SaveFile(OFFICESTUDIO_FILE_IMAGE, L"thumbnail.png", "41false10001000"); * @return Process x2t return code */ int SaveFile(const int& type, const wchar_t* path, const wchar_t* params = 0); @@ -372,7 +403,7 @@ namespace NSDoctRenderer */ void CloseFile(); /** - * Executes the command which will be used to create the document file (text document, spreadsheet, PDF, etc.). + * Executes the command which will be used to create the document file (text document, spreadsheet, presentation, form document, PDF). * @param command The command in the form of JavaScript code which will be used to create the document file (in C++, the escape character must be used when the command contains quotation symbols). * @param retValue The command return value. * @return True if the operation is successful @@ -380,10 +411,10 @@ namespace NSDoctRenderer bool ExecuteCommand(const wchar_t* command, CDocBuilderValue* retValue = 0); /** - * Runs ONLYOFFICE Document Builder executable. If you do not want to write a C++ application, + * Runs the ONLYOFFICE Document Builder executable. If you do not want to write a C++ application, * you can simply use the docbuilder.exe executable file and run it with the .docbuilder file as an argument, - * where all the code for the document file creation will be written. For C++, use the path to the - * executable file from the sPath parameter, create the CDocBuilder object and call the Run method. + * where all the code for the document file creation will be written. For C++, create the CDocBuilder object + * and call the Run method with the path to the executable file from the sPath parameter. * @param path The path to the ONLYOFFICE Document Builder executable. * @return True if the operation is successful */ @@ -393,7 +424,7 @@ namespace NSDoctRenderer * Runs all the commands for the document creation using a single command. * Compared to ExecuteCommand where only one command at a time is allowed, RunText(W)/(A) * makes it possible to enter all the commands for the document creation at once. - * @param commands The commands in Unicode format which will be used to create the document file + * @param commands The commands in the Unicode or UTF8 format which will be used to create the document file * (in C++, the escape character must be used when the command contains quotation symbols). * All the commands containing builder. are line separated, i.e. you cannot write them in one line, each command must start with its own line. * @return True if the operation is successful @@ -402,7 +433,7 @@ namespace NSDoctRenderer bool RunTextA(const char* commands); /** - * Sets an argument to the builder class which can be trasferred to the program outside the CDocBuilder.ExecuteCommand method, + * Sets an argument in the UTF8 format to the builder class which can be trasferred to the program outside the CDocBuilder.ExecuteCommand method, * i.e. either as an additional property when running ONLYOFFICE Document Builder executable file or as a part of program code, but not included into the document file script. * Supported properties: * --use-doctrenderer-scheme - Specifies if the doctrenderer mode is used when building a document or getting content from the editor when saving a file (true/false). @@ -416,21 +447,26 @@ namespace NSDoctRenderer * --save-use-only-names - Specifies if the destination paths are used (for server work) (true/false). For example: /home/user/1.txt => /tmp/1.txt * Default: false * --all-fonts-path - The path to the AllFonts.js script. - * --argument - The JSON argument which is sent to the global parameters of all the opened js context. + * --argument - The JSON argument which is sent to the global parameters of all the opened JS context. * --fonts-system - Specifies if the system fonts are used (true/false). * Default: true * --fonts-dir - The path to the additional fonts directory (may be many records). - * @param param The parameter name in UTF8 format, the value is always --argument. - * @param value The parameter value in UTF8 format, which will be used in the document. + * @param param The parameter name in the UTF8 format, the value is always --argument. + * @param value The parameter value in the UTF8 format, which will be used in the document. */ void SetProperty(const char* param, const wchar_t* value); /** * The Unicode version of the SetProperty method. + * @param param The parameter name in the Unicode format, the value is always --argument. + * @param value The parameter value in the Unicode format, which will be used in the document. */ void SetPropertyW(const wchar_t* param, const wchar_t* value); /** - * Writes data to the file. Used for logs in js code. + * Writes data to the log file. It is used for logs in JS code. + * @param path The path to the file where all the logs will be written. + * @param value The data which will be written to the log file. + * @param append Specifies if the new data will be appended to the already existing log file or a new file will be created. */ void WriteData(const wchar_t* path, const wchar_t* value, const bool& append); @@ -441,28 +477,29 @@ namespace NSDoctRenderer bool IsSaveWithDoctrendererMode(); /** - * Returns the document builder engine version. - * @return The document builder engine version + * Returns the ONLYOFFICE Document Builder engine version. + * @return The ONLYOFFICE Document Builder engine version */ char* GetVersion(); /** - * Returns the current js context. - * @return The current js context + * Returns the current JS context. + * @return The current JS context */ CDocBuilderContext GetContext(); public: /** * Initializes the ONLYOFFICE Document Builder as a library for the application to be able to work with it. - * This method just sets the directory to the main builder resources (icu files and etc). If this method is not called, - * the builder will find resources from the current process directory. + * This method just sets the directory to the main Document Builder resources (icu files, etc). If this method is not called, + * the Document Builder will find resources from the current process directory. + * @param directory The path to the main Document Builder resources. */ static void Initialize(const wchar_t* directory = 0); /** * Unloads the ONLYOFFICE Document Builder from the application memory when it is no longer needed. - * Generally, there is no need to dispose js before exiting - * the process, it should happen automatically. It should only be used if the process needs the resources taken up by js. + * Generally, there is no need to dispose JS before exiting + * the process, it should happen automatically. It should only be used if the process needs the resources taken up by JS. */ static void Dispose(); @@ -479,35 +516,36 @@ namespace NSDoctRenderer /** * Attention!!! - * If you use the builder as both an application and a script, then you need to know some limitations. + * If you use ONLYOFFICE Document Builder as both an application and a script, then you need to know some rules and limitations: * - * 1) docbuilder.exe "path-to-script.docbuilder" - * This is the same as - * NSDoctRenderer::CDocBuilder::Initialize(); - * CDocBuilder builder; - * builder.Run("path-to-script.docbuilder"); - * NSDoctRenderer::CDocBuilder::Dispose(); + * 1) To run ONLYOFFICE Document Builder executable in the C++ application, use the CDocBuilder.Run method in the following way: + * CDocBuilder::Initialize(sWorkDirectory.c_str()); + * CDocBuilder oBuilder; + * oBuilder.Run("path-to-script.docbuilder"); + * CDocBuilder::Dispose(); + * Another way to do this is to use the docbuilder.exe executable file and run it with the .docbuilder file as an argument, + * where all the code for the document file creation will be written: + * docbuilder.exe "path-to-script.docbuilder" * - * 2) argument + * 2) To set an argument to the builder class which can be trasferred to the program outside the CDocBuilder.ExecuteCommand method, + * add it as an additional property when running ONLYOFFICE Document Builder executable file or as a part of program JavaScript code, + * but not included into the document file script. + * Sets the --argument property to CDocBuilder.Run: * docbuilder.exe "--argument={\"company\":\"ONLYOFFICE\",\"product\":\"ONLYOFFICE Document Builder\"}" "path-to-script.docbuilder" - * This sets the --argument property to CDocBuilder & Run (see point 1) - * Using JavaScript: - * var sCompany = Argument["company"]; + * Sets the --argument property using JavaScript code: + * var sCompany = Argument["company"]; * var sProduct = Argument["product"]; * - * 3) Methods of the "builder" object cannot be called with js variables. - * If necessary, wrap it in the "jsValue" instruction, e.g.: + * 3) The builder object methods cannot be called with the JS variables. Wrap them with the jsValue instruction if necessary: * var jsVar = "123.docx"; - * builder.SaveFile("docx", jsVar); // ERROR - * builder.SaveFile("docx", jsValue(jsVar)); // GOOD + * builder.SaveFile("docx", jsVar); // Incorrect + * builder.SaveFile("docx", jsValue(jsVar)); // Correct * - * 4) For convenience, format types have been replaced with strings: - * builder.CreateFile("docx"); - * This is the same as CDocBuilder.CreateFile(AVS_OFFICESTUDIO_FILE_DOCUMENT_DOCX); - * builder.SaveFile("docx", file_path); - * This is the same as CDocBuilder.SaveFile("docx", file_path); + * 4) For convenience, format types are replaced with strings. + * For example, builder.CreateFile("docx"); is the same as CDocBuilder.CreateFile(AVS_OFFICESTUDIO_FILE_DOCUMENT_DOCX); + * And builder.SaveFile("docx", file_path); is the same as CDocBuilder.SaveFile("docx", file_path); * - * All names: + * All format types: * "docx": AVS_OFFICESTUDIO_FILE_DOCUMENT_DOCX; * "doc": AVS_OFFICESTUDIO_FILE_DOCUMENT_DOC; * "odt": AVS_OFFICESTUDIO_FILE_DOCUMENT_ODT; @@ -524,34 +562,31 @@ namespace NSDoctRenderer * "jpg": AVS_OFFICESTUDIO_FILE_IMAGE; * "png": AVS_OFFICESTUDIO_FILE_IMAGE; * - * 5) The entire JavaScript context is a wrapper over its native CDocBuilder object: builderJS. - * You need to work with it as with an ordinary JavaScript object. The jsValue instruction is not needed: + * 5) The entire JavaScript context is a wrapper for its native CDocBuilder builderJS object. You need to work with it as with an ordinary JavaScript object. + * In this case, the jsValue instruction is not needed for the JS variables: * - * builderJS methods: * builderJS.OpenFile("path_or_url", "x2t_additons_as_xml"); * builderJS.CreateFile(AVS_OFFICESTUDIO_FILE_DOCUMENT_DOCX); or builderJS.CreateFile("docx"); * builderJS.SetTmpFolder("folder"); * builderJS.SaveFile(AVS_OFFICESTUDIO_FILE_DOCUMENT_DOCX, "path", "x2t_additons_as_xml"); or builderJS.SaveFile("docx", "path", "x2t_additons_as_xml"); * builderJS.CloseFile(); * - * Attention: The fourth rule does not work for the builderJS object. - * - * 6) The builder always works with one file. - * But there are times when you need to be able to open another file not for adding to the content, - * but for some manipulations (comparing, mailmerge). For such cases, the builder provides the OpenTmpFile method: + * 6) The Document Builder always works with one file. + * But there are cases when you need to be able to open another file not for adding its data to the content, but for some kind of manipulation (document comparison, mailmerge, etc). + * For such cases, the Document Builder provides the OpenTmpFile method: * * var tmpFile = builderJS.OpenTmpFile("path_or_url"); * * The tmpFile interface: - * IsValid() : returns true if the temporary file is valid - * GetBinary() : returns Uint8Array with the doct/pptt/xlst binary content - * GetFolder() : returns the string path to the temporary folder with the temporary file contents - * Close() : closes the file (removes the temporary folder contents) - * GetImageMap() : returns a dictionary object with the imageId -> imagePath key-value (for inserting into the document) + * IsValid() : specifies if the temporary file is valid (true). + * GetBinary() : returns Uint8Array with the doct/pptt/xlst binary content. + * GetFolder() : returns the string path to the temporary folder with the temporary file contents. + * Close() : closes the file (removes the temporary folder contents). + * GetImageMap() : returns a dictionary object with the imageId -> imagePath key-value pairs (for inserting into the document). * */ - // typedefs for shorter code + // To make the code shorter, use the following type definitions: typedef CDocBuilderValue CValue; typedef CDocBuilderContext CContext; typedef CDocBuilderContextScope CContextScope;