libscotty: scotty.h File Reference

Go to the source code of this file.


Data Structures
struct	SCT_allocator_s
	This structure is used to provide an interface to a memory management system. User can set their own, custom one by calling SCT_SetAllocator. The Init and Close fields are optional, and if set, are called in SCT_Init and SCT_Close respectively. More...
struct	SCT_version_s
	Information on the version of libscotty in use. Represents the library's version as three levels: major revision (increments with massive changes, additions, and enhancements), minor revision (increments with backwards-compatible changes to the major revision), and patchlevel (increments with fixes to the minor revision). More...
Defines
#define	SCT_VERSION_MAJOR 0
	Major version number.
#define	SCT_VERSION_MINOR 1
	Minor version number.
#define	SCT_VERSION_PATCH 1
	Patchlevel version number.
#define	SCT_VERSION(x)
	A macro to retrieve the version number of the libscotty release your program was compiled against. Takes a pointer to SCT_version_t structure.
#define	SCT_MAX_PROMPT 64
	The maximum length of the command prompt.
#define	SCT_CMDLINE_BUFFER_SIZE 1024
	The maximum length of the command line (and, therefore, a command).
#define	SCT_PRINTF_BUFFER_SIZE 32768
	Size of the SCT_Printf buffer in bytes.
#define	SCTE_NO_ERROR 0
	No errors occured since the last SCT_GetError call.
#define	SCTE_ERROR_CREATING_WINDOW 1
	An error occured during the creation of any of the curses windows. This error can only be generated in SCT_Init. When this occurs, SCT_Close is called and libscotty remains uninitialized.
#define	SCTE_INVALID_WINDOW_ID 2
	User passed an invalid SCT_window_t enum to SCT_GetWindowHandle.
#define	SCTE_MEMORY_ALLOCATION_FAILED 3
	Last memory allocation failed. When this occurs, libscotty calls SCT_Close() and is unoperable until it is initialized again.
Typedefs
typedef struct SCT_allocator_s	SCT_allocator_t
typedef struct SCT_version_s	SCT_version_t
Enumerations
enum	SCT_window_t { SCT_SCREEN, SCT_OUTPUT, SCT_INPUT }
	An enum used as an argument to SCT_GetWindowHandle(), in case the user wishes to mess with the curses windows themselves. More...
Functions
int	SCT_Init (void)
	Initializes libscotty. Must be called before any other libscotty function.
int	SCT_IsInit (void)
	Checks whether libscotty is initalized.
void	SCT_GetLinkedVersion (SCT_version_t *ver)
	Get the version of libscotty that is linked against your program.
int	SCT_SetAllocator (SCT_allocator_t *alloc)
	This function is provided so that user can use their own set of memory management functions (i.e. malloc/free).
void	SCT_SetCommandHandlerFunction (void(cmdEvFunc)(const char cmd))
	Sets the internal pointer to the function libscotty is supposed to call when a command is entered.
int	SCT_SetHistorySize (unsigned int size)
	Sets the size of the command history (i.e. how many commands will libscotty keep record of; by default it does not at all).
void	SCT_ClearHistory (void)
	Clears the current command history.
void *	SCT_GetWindowHandle (SCT_window_t window)
	This function is provided in case the user wishes to manipulate the curses windows directly. If you don't want to, you can safely ignore it.
int	SCT_GetError (void)
	Retrieves the code of the last error. A subsequent call, unless, of course, an error occurs in the meantime, will return SCTE_NO_ERROR.
int	SCT_AddCompletionEntry (const char *str)
	Adds a new command completion entry.
int	SCT_RemoveCompletionEntry (const char *str)
	Removes a command completion entry from the list.
void	SCT_SetPrompt (const char *prompt)
	Sets a new command prompt.
void	SCT_Echo (const char *str)
	Prints the given string to console.
void	SCT_Printf (const char *fmt,...)
	An equivalent of the stdio printf function.
void	SCT_ClearScreen (void)
	Clears the output window.
int	SCT_Input (void)
	Reads exactly one character (keystroke) and appends it to the commandline buffer. If the enter key is received, the function defined by calling SCT_SetCommandHandlerFunction is called.
int	SCT_Close (void)
	Deallocates all the used memory and shuts down curses.

Detailed Description

Define Documentation

#define SCT_MAX_PROMPT 64

The maximum length of the command prompt.

See also:: SCT_SetPrompt

#define SCT_PRINTF_BUFFER_SIZE 32768

Size of the SCT_Printf buffer in bytes.

See also:: SCT_Printf

#define SCT_VERSION ( x )

Value:

{ \
                                        (x)->major = SCT_VERSION_MAJOR; \
                                        (x)->minor = SCT_VERSION_MINOR; \
                                        (x)->patch = SCT_VERSION_PATCH; \
                                    }

A macro to retrieve the version number of the libscotty release your program was compiled against. Takes a pointer to SCT_version_t structure.

See also:

#define SCT_VERSION_MAJOR 0

Major version number.

See also:

#define SCT_VERSION_MINOR 1

Minor version number.

See also:

#define SCT_VERSION_PATCH 1

Patchlevel version number.

See also:

#define SCTE_ERROR_CREATING_WINDOW 1

An error occured during the creation of any of the curses windows. This error can only be generated in SCT_Init. When this occurs, SCT_Close is called and libscotty remains uninitialized.

See also:: SCT_Init

#define SCTE_INVALID_WINDOW_ID 2

User passed an invalid SCT_window_t enum to SCT_GetWindowHandle.

See also:: SCT_GetWindowHandle

#define SCTE_MEMORY_ALLOCATION_FAILED 3

Last memory allocation failed. When this occurs, libscotty calls SCT_Close() and is unoperable until it is initialized again.

See also:: SCT_SetAllocator

#define SCTE_NO_ERROR 0

No errors occured since the last SCT_GetError call.

See also:: SCT_GetError

Enumeration Type Documentation

enum SCT_window_t

An enum used as an argument to SCT_GetWindowHandle(), in case the user wishes to mess with the curses windows themselves.

See also:: SCT_GetWindowHandle

Function Documentation

void SCT_AddCompletionEntry ( const char * str )

Adds a new command completion entry.

Command completion can be triggered by typing the first few characters of a command and pressing tab. It works for the whole command line, which means completion entries can contain spaces.

Parameters:

str

A null-terminated string containing the command libscotty should attempt to complete. An internal copy of it is made.

Returns:: Nonzero on success, zero on failure. Call SCT_GetError to retrieve the error code.

See also:: SCT_RemoveCompletionEntry

void SCT_ClearHistory ( void )

Clears the current command history.

See also:: SCT_SetHistorySize

int SCT_Close ( void )

Deallocates all the used memory and shuts down curses.

Returns:: Nonzero on success, zero on failure.

void SCT_Echo ( const char * str )

Prints the given string to console.

Note:: This just dumps the string in the output window. If you'd like to use formatted output, see SCT_Printf.

Parameters:

str

A null terminated string. Mind you that no sanity check is done, the function will keep printing characters until any zero is found.

See also:: SCT_Printf

int SCT_GetError ( void )

Retrieves the code of the last error. A subsequent call, unless, of course, an error occurs in the meantime, will return SCTE_NO_ERROR.

Returns:: The error code.

See also:

SCTE_NO_ERROR

SCTE_ERROR_CREATING_WINDOW

SCTE_INVALID_WINDOW_ID

SCTE_MEMORY_ALLOCATION_FAILED

void SCT_GetLinkedVersion ( SCT_version_t * ver )

Get the version of libscotty that is linked against your program.

If you are using a shared library (DLL) version of libscotty, it is possible that it will be different than the version you compiled against. This is a real function; the macro SCT_VERSION tells you what version of libscotty you compiled against.

Parameters:

ver

A pointer to an existing SCT_version_t struct.

See also:

void * SCT_GetWindowHandle ( SCT_window_t window )

This function is provided in case the user wishes to manipulate the curses windows directly. If you don't want to, you can safely ignore it.

Parameters:

window

An SCT_window_t enum.

Returns:: A curses WINDOW * pointer cast to void * on success, NULL on failure. Call SCT_GetError to retrieve the error code.

See also:: SCT_window_t
SCT_GetError

int SCT_Init ( void )

Initializes libscotty. Must be called before any other libscotty function.

Warning:: This function will clear the screen entirely.

Returns:: Nonzero on succes, zero on error. Use SCT_GetError to retrieve the error code.

See also:: SCT_GetError
SCT_SetCommandHandlerFunction

void SCT_Input ( void )

Reads exactly one character (keystroke) and appends it to the commandline buffer. If the enter key is received, the function defined by calling SCT_SetCommandHandlerFunction is called.

User's application should call this function in a loop as long as it wants to receive input, preferably in a separate thread.

Note:: Commands > SCT_CMDLINE_BUFFER_SIZE will be truncated. The moment SCT_CMDLINE_BUFFER_SIZE number is hit, the command is passed on to command handler function just as if enter was pressed.

Returns:: Nonzero on success, zero on failure. Call SCT_GetError to retrieve the error code.

See also:: SCT_SetCommandHandlerFunction
SCT_CMDLINE_BUFFER_SIZE

int SCT_IsInit ( void )

Checks whether libscotty is initalized.

Returns:: Nonzero between calls of SCT_Init and SCT_Close, zero otherwise.

See also:: SCT_Init
SCT_Close

void SCT_Printf	(	const char *	fmt,
			...
	)

An equivalent of the stdio printf function.

Does this really need an explanation?

Note:: The maximum length of a string to print is SCT_PRINTF_BUFFER_SIZE, anything longer will be truncated. If you need a function to simply dump a string to the output window without formatting, see SCT_Echo.

See also:: SCT_PRINTF_BUFFER_SIZE
SCT_Echo

int SCT_RemoveCompletionEntry ( const char * str )

Removes a command completion entry from the list.

Parameters:

str

A null-terminated string containing the completion entry to remove.

Returns:: Nonzero if the entry was found and removed, zero if it was not.

See also:: SCT_AddCompletionEntry

int SCT_SetAllocator ( SCT_allocator_t * alloc )

This function is provided so that user can use their own set of memory management functions (i.e. malloc/free).

By default, libscotty will use stdlib's malloc and free functions. Unless you have custom memory management routines, you can safely ignore this.

Warning:: You can only set a new allocator during the time when libscotty is not initialized (that is, when SCT_IsInit returns 0). Otherwise, the call will fail.

Parameters:

alloc

A pointer to a SCT_allocator_t struct containing the pointers to the relevant functions. Pass NULL to fall back to default stdlib ones.

Returns:: Nonzero on success, zero on failure.

See also:: SCT_allocator_s

void SCT_SetCommandHandlerFunction ( void(*)(const char *cmd) cmdEvFunc )

Sets the internal pointer to the function libscotty is supposed to call when a command is entered.

Note:: It is advisable to call it right after initializing the library. You will not be able to retrieve the commands without it.

Parameters:

cmdEvFunc

A pointer to a function taking a string (const char *) as the single parametre. Libscotty will call it with an entire command (a null-terminated, READ-ONLY string) as argument. Pass NULL to disable command notification (why would anyone want to do that?).

int SCT_SetHistorySize ( unsigned int size )

Sets the size of the command history (i.e. how many commands will libscotty keep record of; by default it does not at all).

Note:: Calling this clears the current history.

Parameters:

size

New number of entries to keep. 0 disables history altogether.

Returns:: Nonzero on success, zero on failure. Call SCT_GetError to retrieve the error code.

See also:: SCT_ClearHistory

void SCT_SetPrompt ( const char * prompt )

Sets a new command prompt.

An internal copy of the given string is created.

Note:: This function forces a redraw of the input line. Command line remains untouched.

Parameters:

prompt

A null-terminated string containing the new command prompt. If its length is over SCT_MAX_PROMPT chars, it will be clipped.

See also:: SCT_MAX_PROMPT

scotty.h File Reference

Data Structures

Defines

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Enumeration Type Documentation

Function Documentation