www.beck-ipc.com

@CHIP-RTOS C Library V2.00 - BIOS API


BIOS_Install_User_Stdio

Install user specific stdio handlers.

void BIOS_Install_User_Stdio ( const USER_STDIO_FUNCS far *vectors );

Parameters

vectors

Pointer to a USER_STDIO_FUNCS type data structure prepared by caller.  Set this parameter to null to uninstall the user's device handlers.

Return Value

-- none --

Comments

This function installs user specific stdio channel handlers, allowing the user to connect their own input/output device such as a display or keyboard to the IPC@CHIP.   A TCP application similar to Telnet would be another example.

The user must implement four functions in their application to cover reading and writing characters from/to their new stdin/stdout device.   After installing these functions with this API call and then setting stdin and/or stdout to the new user channel with the BIOS_Select_Stdio   API, the @Chip-RTOS will call these user functions at each stdin and stdout operation.

The following type definitions can be found in BIOS_API.H header file:

typedef int huge (far *USER_KBHIT) (void);
typedef void huge(far *USER_PUTCH) (char chr);
typedef void huge(far *USER_PUTSTR) (const char far * pch, int n);
typedef int huge (far *USER_GETCH) (void);


typedef struct tag_user_stdio
{
         USER_KBHIT   user_kbhit;
         USER_GETCH   user_getch;
         USER_PUTCH   user_putch;
         USER_PUTSTR user_putstr;
} USER_STDIO_FUNCS;


Functions to be implemented by the user:

// user_kbhit returns a 1 if a character is available, 0 if not.
int huge user_kbhit(void);

// user_getch reads a char from stdin (waits if none available)
int huge user_getch(void);

// user_putch writes a single character to stdout
void huge user_putch(char chr);     //write a single char to stdout

// user_putstr writes a string of n characters to stdout
void huge user_putstr(const char far * pch, int n);

The user must set the vectors to this set of four callback functions in the USER_STDIO_FUNCS structure referenced by the vectors input parameter.

The user handlers are uninstalled by calling this API with the vectors parameter set to zero.

Important :

    1. The USER_STDIO_FUNCS data structure must be static.   The @Chip-RTOS does not make a copy of this information, but instead references this provided data structure during operation.
    2. If your application exits, don't forget to uninstall your stdio handler by calling this API call with vectors parameter set to zero.
    3. Do not call your stdio functions from within your application, these functions must only be called from the @Chip-RTOS.

Example (Borland C):

USER_STDIO_FUNCS user_stdio_funcs ;    // global variable

// implementations of user's stdio functions
int  huge my_kbhit(void)
{
   //........
}

int huge my_getch(void)
{
   //........
}

void huge my_putch(char chr)
{
   //........
}

void huge my_putstr (const char * pch, int n)
{
   //.......
}

void install_my_stdio_channel (void)
{
   user_stdio_funcs.user_kbhit  = my_kbhit;
   user_stdio_funcs.user_getch  = my_getch;
   user_stdio_funcs.user_putch  = my_putch;
   user_stdio_funcs.user_putstr = my_putstr;

   BIOS_Install_User_Stdio ( &user_stdio ) ;
   BIOS_Select_Stdio ( STDIO_COM | STDIO_TELNET | STDIO_USER, // ports
		   SET_STDOUT | SET_STDIN) ;              // direction
}

void remove_my_stdio_channel (void)
{
   BIOS_Select_Stdio ( STDIO_COM | STDIO_TELNET,              // ports
		   SET_STDOUT | SET_STDIN) ;              // direction

   BIOS_Install_User_Stdio ( 0 ) ;             // un-install
}

int main (void)
{
   //......
   install_my_stdio_channel();
   //....

   // at the end of the program
   remove_my_stdio_channel():
}

See Also

RTOS API

This library function invokes a RTOS software interrupt. Refer to this RTOS API function's documentation for more details.


This API List
List of C Libraries
@CHIP-RTOS Main Index


End of document