@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
|