interpreter.h File Reference

The command interpreter functions. More...

#include "common.h"

Go to the source code of this file.

Macros
#define	PQS_INTERPRETER_COMMAND_BUFFER_SIZE   128
	The command buffer size.
#define	PQS_INTERPRETER_COMMAND_EXECUTE_SIZE   10240000
	The command execute buffer size.

Functions
PQS_EXPORT_API bool	pqs_interpreter_extract_paramater (char *param, const char *message)
	Extract a parameter from a string.
PQS_EXPORT_API bool	pqs_interpreter_extract_paramaters (char *param1, char *param2, const char *message)
	Extract two parameters from a string.
PQS_EXPORT_API size_t	pqs_interpreter_file_to_stream (uint8_t *result, size_t reslen, const char *parameter)
	Copy a file to a byte array.
PQS_EXPORT_API size_t	pqs_interpreter_file_buffer_length (const char *parameter)
	Get the length of a file.
PQS_EXPORT_API size_t	pqs_interpreter_stream_to_file (uint8_t *result, size_t reslen, const char *parameter, size_t parlen)
	Copy a byte stream to a file.
PQS_EXPORT_API size_t	pqs_interpreter_command_execute (char *result, size_t reslen, const char *parameter)
	Execute a command and return its output.
PQS_EXPORT_API bool	pqs_interpreter_initialize ()
	Initialize the command interpreter.
PQS_EXPORT_API void	pqs_interpreter_cleanup ()
	Clean up the command interpreter.

Detailed Description

The command interpreter functions.

This header defines the functions and macros used to implement the command interpreter for PQS. The interpreter supports operations such as parameter extraction from command strings, converting files to and from byte streams, and executing system commands with their output captured. Platform-specific support is provided for Windows and non-Windows systems.

The public API includes functions to initialize and clean up the interpreter, extract parameters, perform file I/O operations, and execute commands.

Macro Definition Documentation

PQS_INTERPRETER_COMMAND_BUFFER_SIZE

#define PQS_INTERPRETER_COMMAND_BUFFER_SIZE   128

The command buffer size.

This macro defines the size (in bytes) of the buffer used for reading command output.

PQS_INTERPRETER_COMMAND_EXECUTE_SIZE

#define PQS_INTERPRETER_COMMAND_EXECUTE_SIZE   10240000

The command execute buffer size.

This macro defines the maximum size (in bytes) for the output buffer when executing a command.

Function Documentation

pqs_interpreter_cleanup()

PQS_EXPORT_API void pqs_interpreter_cleanup

(

)

Clean up the command interpreter.

This function releases resources allocated by the command interpreter. On Windows, it terminates the command process and closes any associated handles.

pqs_interpreter_command_execute()

PQS_EXPORT_API size_t pqs_interpreter_command_execute	(	char *	result,
		size_t	reslen,
		const char *	parameter )

Execute a command and return its output.

This function executes a system command specified by the parameter string and captures its output. The command output is stored in the provided result buffer.

Parameters

result	The output buffer that will receive the command result string.
reslen	The length (in bytes) of the result buffer.
parameter	[const] The command string to be executed.

Returns

Returns the number of bytes written to the result buffer containing the command output.

pqs_interpreter_extract_paramater()

PQS_EXPORT_API bool pqs_interpreter_extract_paramater	(	char *	param,
		const char *	message )

Extract a parameter from a string.

This function searches the input message string for a parameter by locating the first space character and extracting the substring that follows. The extracted parameter is copied into the provided buffer.

Parameters

param	The output buffer that will receive the parameter string.
message	[const] The input message string containing the parameter.

Returns

Returns true if a parameter was successfully extracted; otherwise, false.

pqs_interpreter_extract_paramaters()

PQS_EXPORT_API bool pqs_interpreter_extract_paramaters	(	char *	param1,
		char *	param2,
		const char *	message )

Extract two parameters from a string.

This function parses the input message string to extract two separate parameters. It uses delimiters, such as a comma and space, to determine the boundaries of each parameter and copies the resulting substrings into the provided buffers.

Parameters

param1	The output buffer for the first parameter.
param2	The output buffer for the second parameter.
message	[const] The input message string containing the parameters.

Returns

Returns true if the parameters were successfully extracted; otherwise, false.

pqs_interpreter_file_buffer_length()

PQS_EXPORT_API size_t pqs_interpreter_file_buffer_length

(

const char *

parameter

)

Get the length of a file.

This function retrieves the size (in bytes) of a file specified by the parameter string. It extracts the file path and queries the file system to determine the file length.

Parameters

parameter

[const] The file path or paths string.

Returns

Returns the length of the file in bytes.

pqs_interpreter_file_to_stream()

PQS_EXPORT_API size_t pqs_interpreter_file_to_stream	(	uint8_t *	result,
		size_t	reslen,
		const char *	parameter )

Copy a file to a byte array.

This function reads the contents of a file specified by the parameter string and writes the file data into a provided byte array. The output includes a constructed result string that contains the file path, name, and extension followed by the file data.

Parameters

result	The output byte array that will receive the file stream.
reslen	The length (in bytes) of the result buffer.
parameter	[const] The parameter string specifying the file to be read.

Returns

Returns the total number of bytes written to the result stream.

pqs_interpreter_initialize()

PQS_EXPORT_API bool pqs_interpreter_initialize

(

)

Initialize the command interpreter.

This function initializes the interpreter. On Windows systems, it creates pipes and launches a hidden command shell (cmd.exe) to execute commands. On non-Windows systems, it sets the internal state to active.

Returns

Returns true if the interpreter was successfully initialized; otherwise, false.

pqs_interpreter_stream_to_file()

PQS_EXPORT_API size_t pqs_interpreter_stream_to_file	(	uint8_t *	result,
		size_t	reslen,
		const char *	parameter,
		size_t	parlen )

Copy a byte stream to a file.

This function writes the data from a byte stream to a file. The file destination is determined by the parameter string, and the number of bytes to write is given by the parameter length.

Parameters

result	The output parameter result string.
reslen	The length (in bytes) of the result buffer.
parameter	[const] The parameter string specifying the destination file.
parlen	The length (in bytes) of the parameter string.

Returns

Returns the number of bytes written to the file.