LibRTOSConsole-C-Library 1.0
Library Code documentation
Loading...
Searching...
No Matches
Console.h File Reference
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs

typedef struct ConsoleHandle * ConsoleHandle_t
 
typedef int(* CONSOLE_CommandFunc) (int argc, char **argv, void *context)
 
typedef int(* ConsoleReadStream_t) (void *pContext, char *pBuffer, int num)
 
typedef int(* ConsoleWriteStream_t) (void *pContext, const char *pBuffer, int num)
 

Functions

ConsoleHandle_t CONSOLE_CreateInstance (unsigned int uxStackDepth, int xPrio)
 
void CONSOLE_DestroyInstance (ConsoleHandle_t h)
 
int CONSOLE_RegisterCommand (ConsoleHandle_t h, char *cmd, char *help, CONSOLE_CommandFunc func, void *context)
 
int CONSOLE_RegisterAlias (ConsoleHandle_t h, char *cmd, char *aliasCmd)
 
int CONSOLE_RemoveAliasOrCommand (ConsoleHandle_t h, char *cmd)
 
int CONSOLE_RedirectStreams (ConsoleHandle_t h, ConsoleReadStream_t rdFunc, ConsoleWriteStream_t wrFunc, void *rdContext, void *wrContext)
 

Typedef Documentation

◆ CONSOLE_CommandFunc

typedef int(* CONSOLE_CommandFunc) (int argc, char **argv, void *context)

The CONSOLE_CommandFunc function pointer type is used to describe the arguments which are passed by the console processor toi the registered console function. The user gets the classical argc and argv arguments which are known well from a standard main in nearly any programming language. There is an additional context pointer, which optionally holds additional information. The pointer to this information is passed with the registration of the command by the user and can not be changed anymore at runtime

The return value of a console function is always zero on success or any non zero number when an error occured. The standard is more or less a non zero number which is smaller than 0.

◆ ConsoleHandle_t

typedef struct ConsoleHandle* ConsoleHandle_t

The ConsoleHandle_t handle is an instance pointer of the console library which is generated whenever the CONSOLE_CreateInstance function returns with success.

◆ ConsoleReadStream_t

typedef int(* ConsoleReadStream_t) (void *pContext, char *pBuffer, int num)

ConsoleReadStream_t should return -1 on failure, or else the number of bytes read (0 on EOF). It is similar to syscall <<read>>, except that <int> rather than <size_t> bounds a transaction size, and <[context]> will be passed as the first argument.

◆ ConsoleWriteStream_t

typedef int(* ConsoleWriteStream_t) (void *pContext, const char *pBuffer, int num)

ConsoleWriteStream_t should return -1 on failure, or else the number of bytes written. It is similar to <<write>>, except that <int> rather than <size_t> bounds a transaction size, and <[cookie]> will be passed as the first argument.

Function Documentation

◆ CONSOLE_CreateInstance()

ConsoleHandle_t CONSOLE_CreateInstance ( unsigned int uxStackDepth,
int xPrio )

The CONSOLE_CreateInstance function is used to create the console processor. There is no singleton pattern implemented for the console but as there is no stream abstraction for the console processor, it only makes sense to have one instance at runtime!

The return value of a console function is a null pointer in case an error occured or a pointer of type ConsoleHandle_t.

Parameters
uxStackDepthis the stack depth of the console processor thread in words
xPriois the console processor priority. This should always be on a low level because the stdlib function may not block and so the processor always runs whenever it can. In case the reception of the newlib is blocking and interrupt based, the priority could be higher!

◆ CONSOLE_DestroyInstance()

void CONSOLE_DestroyInstance ( ConsoleHandle_t h)

The CONSOLE_DestroyInstance function is used to cleanup all used ressources which then stops the console processor. This leads to the case that no console functionallity is provided in the design anymore

◆ CONSOLE_RedirectStreams()

int CONSOLE_RedirectStreams ( ConsoleHandle_t h,
ConsoleReadStream_t rdFunc,
ConsoleWriteStream_t wrFunc,
void * rdContext,
void * wrContext )

The CONSOLE_RedirectStreams function is used to change stdin or stdout as default streams for the console functions. In case one or both stream function pointers are NULL, it will be set back to stdin respectively stdout. In case of an error, the last stream configuration is kept and -1 is returned, otherwise 0

Parameters
his of type ConsoleHandle_t which is created by a call of CONSOLE_CreateInstance
rdFuncis of type ConsoleReadStream_t which is the new stream read function for the command processor
wrFuncis of type ConsoleWriteStream_t which is the new stream write function for the command processor

NOTE it might be that not on all platforms it is possible to use this function, it then returns -2 if it is not implemented properly. So far only newlib stdlib is supported!

◆ CONSOLE_RegisterAlias()

int CONSOLE_RegisterAlias ( ConsoleHandle_t h,
char * cmd,
char * aliasCmd )

The CONSOLE_RegisterAlias function is used to register custom commands which can be mapped to other commands when the user enters the given alias command string. Arguments will not be passed from an alias command to the mapped command, so the alias should be specified with the required commands accordingly

Parameters
his of type ConsoleHandle_t which is created by a call of CONSOLE_CreateInstance
cmdis of type char* which is the case sensitive name of the alias command
aliasCmdis of type char* which is the mapped command and its args and is visible when the user types help

◆ CONSOLE_RegisterCommand()

int CONSOLE_RegisterCommand ( ConsoleHandle_t h,
char * cmd,
char * help,
CONSOLE_CommandFunc func,
void * context )

The CONSOLE_RegisterCommand function is used to register custom commands which can be called by the console processor when the user enters the given command string. The arguments and an additional context pointer are passed by the console processor to the function as well.

Parameters
his of type ConsoleHandle_t which is created by a call of CONSOLE_CreateInstance
cmdis of type char* which is the case sensitive name of the command
helpis of type char* which is the help text or description of the command when the user types help
funcis of type CONSOLE_CommandFunc which is the function pointer to the command
contextis of type void* which is an optional data pointer which is passed to the function when called

◆ CONSOLE_RemoveAliasOrCommand()

int CONSOLE_RemoveAliasOrCommand ( ConsoleHandle_t h,
char * cmd )

The CONSOLE_RemoveAliasOrCommand function is used to remove custom commands or alias entries which are mapped in the console processor.

Parameters
his of type ConsoleHandle_t which is created by a call of CONSOLE_CreateInstance
cmdis of type char* which is the case sensitive name of the alias or command