[Ccom-develop] ccom/docs ccom._tx,1.5,1.6 readme._tx,1.4,1.5
Brought to you by:
chrisan,
rasmusmyklebust
Menu
▾
▴
[Ccom-develop] ccom/docs ccom._tx,1.5,1.6 readme._tx,1.4,1.5
|
From: Christer S. <ch...@us...> - 2004-06-21 19:18:06
|
Update of /cvsroot/ccomx/ccom/docs In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv15985/docs Modified Files: ccom._tx readme._tx Log Message: fixed some build issues Index: readme._tx =================================================================== RCS file: /cvsroot/ccomx/ccom/docs/readme._tx,v retrieving revision 1.4 retrieving revision 1.5 diff -C2 -d -r1.4 -r1.5 *** readme._tx 8 Feb 2004 20:47:21 -0000 1.4 --- readme._tx 21 Jun 2004 19:17:54 -0000 1.5 *************** *** 1,197 **** ! @# This is the source for the CCOM readme file, in Allegro's custom format. ! @# Read allegro/docs/makedoc.c for a description of what is going on... ! @# ! @#ignore_css ! @multiwordheaders ! @document_title=CCOM readme ! @rtfh=Readme file of CCOM ! @$\input texinfo ! @$@setfilename readme.inf ! @$@settitle Readme of CCOM ! @$@setchapternewpage odd ! @$@paragraphindent 0 ! @$@setchapternewpage off ! @# This should remain commented at the moment (dvi output) @$@finalout ! @$ ! @$@ifinfo ! @$@direntry ! @$* Readme: (readme). Readme in CCOM ! @$@end direntry ! @$This is the Info version of the CCOM readme file. ! @$ ! @$By Christer Sandberg and Rasmus Myklebust ! @$@end ifinfo ! @$ ! @$@node Top, , (dir), (dir) ! @<html> ! @<head> ! @<title>Readme file of CCOM</title> ! @<body> ! <center><b>A CGUI and Allegro addon for serial port communication</b></center> ! <center><b>by Christer Sandberg and Rasmus Myklebust</b></center> ! <center>Email: <email>chr...@md...</a></center> ! <center>Homepage: <a href="http://www.idt.mdh.se/~csg/cgui/cguix">http://www.idt.mdh.se/~csg/cgui/cguix</a></center> ! <center><b> ! Readme file of CCOM ! </b></center> ! @!text ! @heading ! Contents ! ! @shortcontents ! ! @text ! @heading ! Introduction ! ! CCOM is a library with functions for sending and receiving data via the ! serial ports, using the event queue of CGUI. It also provides a dialogue ! that lets the user modify the port settings. ! ! CCOM builds and operates on the following platforms: DOS/DJGPP, Linux, ! Windows/Mingw32 and Windows/MSVC. ! ! @heading ! Requirements ! ! You need to have compiled and installed Allegro version 4.0.x, as well as ! CGUI vesion 1.6.5 or later. ! There are also other requirements like correctly installed compilers etc. ! but these are already fulfilled if you succeded in making and installing ! Allegro and CGUI (no additional requirements are needed). ! ! You can find Allegro at: ! http://alleg.sourceforge.net/ ! ! You can find CGUI at: ! http://www.mdh.se/~csg/cgui/ ! ! ! @heading ! Installation ! ! Installation goes in five simple steps, and should be familiar since it is ! similar to the installation procedure as of Allegro and CGUI: ! <ul> ! <li> ! Tell the installation process what platform you use. Start a command window ! (shell) and set the main directory of CCOM to you current directory ! (i.e. enter the command > cd <the path to your CCOM directory>). Choose ! platform by running one of the following commands:<br> ! <pre> ! fix.bat djgpp - to compile with DOS/DJGPP ! fix.bat mingw32 - to compile with Windows/MinGW32 ! fix.bat msvc - to compile with Windows/MSVC ! ./fix.sh unix - to compile with Linux/gcc ! </pre> ! <li> ! Specify the path to your allegro installation by setting the environment ! variable ALLEGRO. E.g. if your allegro directory is c:\allegro then ! you must type <br> ! <pre> ! set ALLEGRO=c:\allegro ! </pre> ! or alternatively put that line into your autoexec file and restart. ! For unix users: ! <pre> ! export ALLEGRO=/home/user/allegro-4.0.3 ! </pre> ! or whatever is the name of your allegro directory. ! <li> ! Specify the path to your CGUI installation by setting the environment ! CGUIDIR the same way as ALLEGRO, e.g.<br> ! <pre> ! set CGUIDIR=c:\cgui ! </pre> ! <pre> ! export CGUIDIR=/home/user/cgui ! </pre> ! <li> ! Compile the library. This is done by running "make" at the command line. ! <li> ! Install the files to common directories. This is done by running ! "make install" at the command line.<br> ! Under Linux, you may want to instead run "make install SYSTEM_DIR=<dir>", ! which will cause headers to be installed to <dir>/include and libraries to ! <dir>/lib. (default for <dir> is /usr/local), or else you need to ! run make install as root. ! </ul> ! That's it! Now you are ready to run the example program in the example directory. ! <p> ! You may also want to perform some of the optional steps during the installation: ! <ul> ! <li> ! You can compile a debugging library by typing "make DEBUGMODE=1" instead of ! just "make" and "make install DEBUGMODE=1" instead of "make install". ! To compile both the usual and the debug library in one step, ! type "make all" and "make installall".<br> ! These debugging libraries require that you also have maked and installed ! the debugging versions of Allegro and CGUI. ! <li> ! If you want statically linked libraries under Unix or Windows as well as ! the default dynamically linked libraries (dll under Windows, .so under ! Unix), add "STATICLINK=1" to the make command like "make STATICLINK=1", ! or "make DEBUGMODE=1 STATICLINK=1" and also add it to the installation ! command.<br> ! These static libraries require that you also have maked and installed ! the static versions of Allegro and CGUI. ! <li> ! Users of the MSys environment needs to set teh environment vaariable ! UNIX_TOOLS to 1 before make install is run. ! <li> ! If you want to read the CCOM documentation with the Rhide online help ! system, go to the "Help / Syntax help / Files to search" menu in Rhide, ! and add "ccom" after the existing "libc" entry (separated by a space). ! <li> ! To use the ! To use the debugging library, link with libccomd.a instead of libccom.a. ! </ul> ! ! ! @heading ! Usage ! <ul><li> ! #include <ccom.h> in the top of each file that uses a function from ! the library. ! <li> ! Before calling any CCOM functions you must have initialized CGUI, Note! ! CGUI! For info about available functions, please read the manual, e.g. ! ccom.html (but the docs are also available in other formats). ! <li> ! If you link on the command line, link with '-lccom -lcgui -lalleg'. It is ! important that you specify the libraries in that order. If you want the ! ability to debug inside CCOM's functions, then link with '-lccomd' ! instead of '-lccom'. ! <p> ! On Linux you can use the following command to link with the default ! lib of CCOM (please note the ` ) ! <pre> ! gcc -s -lccom -lcgui `allegro-config --libs release --shared` file.o ! </pre> ! where `file' is the name of your file. <br> ! For debug libraries use -lccomd -lcguid instead and replace release ! with debug in the allegro config option. For linking a static application ! use -lccom_s and -lcgui_s and replace --shared with --static. ! <li> ! If you use the RHIDE environment, go to the menu Options/Libraries and ! fill in ccom. It is important that ccom is above cgui and allegro. Don't ! forget to check the box to the left of the library. You have to replace ! ccom with ccomd to include debugging information. ! <li> ! If you use some other environment, there is probably some options dialog ! where you can enter the libraries names (e.g. -lccom -lcgui -lalleg). ! </ul> ! ! ! @heading ! Contact Info ! ! Email:<ul> ! chr...@md... ! </ul> ! Homepage:<ul> ! http://www.idt.mdh.se/~csg/cgui/cguix ! </ul> ! Telephone:<ul> ! +46.(0)21.38.10.66 ! </ul> --- 1,216 ---- ! @# This is the source for the CCOM readme file, in Allegro's custom format. ! @# Read allegro/docs/makedoc.c for a description of what is going on... ! @# ! @#ignore_css ! @multiwordheaders ! @document_title=CCOM readme ! @rtfh=Readme file of CCOM ! @$\input texinfo ! @$@setfilename readme.inf ! @$@settitle Readme of CCOM ! @$@setchapternewpage odd ! @$@paragraphindent 0 ! @$@setchapternewpage off ! @# This should remain commented at the moment (dvi output) @$@finalout ! @$ ! @$@ifinfo ! @$@direntry ! @$* Readme: (readme). Readme in CCOM ! @$@end direntry ! @$This is the Info version of the CCOM readme file. ! @$ ! @$By Christer Sandberg and Rasmus Myklebust ! @$@end ifinfo ! @$ ! @$@node Top, , (dir), (dir) ! @<html> ! @<head> ! @<title>Readme file of CCOM</title> ! @<body> ! <center><b>A CGUI and Allegro addon for serial port communication</b></center> ! <center><b>by Christer Sandberg and Rasmus Myklebust</b></center> ! <center>Email: <email>chr...@md...</a></center> ! <center>Homepage: <a href="http://www.idt.mdh.se/~csg/cgui/cguix">http://www.idt.mdh.se/~csg/cgui/cguix</a></center> ! <center><b> ! Readme file of CCOM ! </b></center> ! @!text ! @heading ! Contents ! ! @shortcontents ! ! @text ! @heading ! Introduction ! ! CCOM is a library with functions for sending and receiving data via the ! serial ports, using the event queue of CGUI. It also provides a dialogue ! that lets the user modify the port settings. ! ! CCOM builds and operates on the following platforms: DOS/DJGPP, Linux, ! Windows/Mingw32 and Windows/MSVC. ! ! @heading ! Requirements ! ! You need to have compiled and installed Allegro version 4.0.x, as well as ! CGUI vesion 1.6.7 or later. ! There are also other requirements like correctly installed compilers etc. ! but these are already fulfilled if you succeded in making and installing ! Allegro and CGUI (no additional requirements are needed). ! ! You can find Allegro at: ! http://alleg.sourceforge.net/ ! ! You can find CGUI at: ! http://www.mdh.se/~csg/cgui/ ! ! ! @heading ! Installation ! ! Installation goes in some simple steps, and should be familiar since it is ! similar to the installation procedure as of Allegro and CGUI: ! <ul> ! <li> ! Tell the installation process what platform you use. Start a command window ! (shell) and set the main directory of CCOM to you current directory ! i.e. enter the command ! <pre> ! cd c:\cbar ! </pre> ! or whatever is the name of your ccom directory. Then choose platform by ! running one of the following commands: ! <pre> ! fix.bat djgpp - to compile with DOS/DJGPP ! fix.bat mingw32 - to compile with Windows/MinGW32 ! fix.bat msvc - to compile with Windows/MSVC ! ./fix.sh unix - to compile with Linux/gcc ! </pre> ! <li> ! Specify the path to your allegro installation by setting the environment ! variable ALLEGRO. E.g. if your allegro directory is c:\allegro then ! you must type <br> ! <pre> ! set ALLEGRO=c:\allegro ! </pre> ! or alternatively put that line into your autoexec file and restart. ! For unix users: ! <pre> ! export ALLEGRO=/home/user/allegro-4.0.3 ! </pre> ! or whatever is the name of your allegro directory. ! <li> ! Specify the path to your CGUI installation by setting the environment ! CGUIDIR the same way as ALLEGRO, e.g.<br> ! <pre> ! set CGUIDIR=c:\cgui ! </pre> ! <pre> ! export CGUIDIR=/home/user/cgui ! </pre> ! <li> ! Ensure that all CGUI's tools has been built: ! Make CGUI's directory to the current, e.g. type the command ! <pre> ! cd c:\cgui ! </pre> ! Build: ! <pre> ! make dat2c ! make mktext ! </pre> ! Return to the main directory of cbar, e.g.: ! <pre> ! cd c:\ccom ! </pre> ! <li> ! Compile the library. This is done by running "make" at the command line. ! <li> ! Install the files to common directories. This is done by running ! "make install" at the command line.<br> ! Under Linux, you may want to instead run "make install SYSTEM_DIR=<dir>", ! which will cause headers to be installed to <dir>/include and libraries to ! <dir>/lib. (default for <dir> is /usr/local), or else you need to ! run make install as root. ! </ul> ! That's it! Now you are ready to run the example program in the example directory. ! <p> ! You may also want to perform some of the optional steps during the installation: ! <ul> ! <li> ! You can compile a debugging library by typing "make DEBUGMODE=1" instead of ! just "make" and "make install DEBUGMODE=1" instead of "make install". ! To compile both the usual and the debug library in one step, ! type "make all" and "make installall".<br> ! These debugging libraries require that you also have maked and installed ! the debugging versions of Allegro and CGUI. ! <li> ! If you want statically linked libraries under Unix or Windows as well as ! the default dynamically linked libraries (dll under Windows, .so under ! Unix), add "STATICLINK=1" to the make command like "make STATICLINK=1", ! or "make DEBUGMODE=1 STATICLINK=1" and also add it to the installation ! command.<br> ! These static libraries require that you also have maked and installed ! the static versions of Allegro and CGUI. ! <li> ! Users of the MSys environment needs to set teh environment vaariable ! UNIX_TOOLS to 1 before make install is run. ! <li> ! If you want to read the CCOM documentation with the Rhide online help ! system, go to the "Help / Syntax help / Files to search" menu in Rhide, ! and add "ccom" after the existing "libc" entry (separated by a space). ! <li> ! To use the ! To use the debugging library, link with libccomd.a instead of libccom.a. ! </ul> ! ! ! @heading ! Usage ! <ul><li> ! #include <ccom.h> in the top of each file that uses a function from ! the library. ! <li> ! Before calling any CCOM functions you must have initialized CGUI, Note! ! CGUI! For info about available functions, please read the manual, e.g. ! ccom.html (but the docs are also available in other formats). ! <li> ! If you link on the command line, link with '-lccom -lcgui -lalleg'. It is ! important that you specify the libraries in that order. If you want the ! ability to debug inside CCOM's functions, then link with '-lccomd' ! instead of '-lccom'. ! <p> ! On Linux you can use the following command to link with the default ! lib of CCOM (please note the ` ) ! <pre> ! gcc -s -lccom -lcgui `allegro-config --libs release --shared` file.o ! </pre> ! where `file' is the name of your file. <br> ! For debug libraries use -lccomd -lcguid instead and replace release ! with debug in the allegro config option. For linking a static application ! use -lccom_s and -lcgui_s and replace --shared with --static. ! <li> ! If you use the RHIDE environment, go to the menu Options/Libraries and ! fill in ccom. It is important that ccom is above cgui and allegro. Don't ! forget to check the box to the left of the library. You have to replace ! ccom with ccomd to include debugging information. ! <li> ! If you use some other environment, there is probably some options dialog ! where you can enter the libraries names (e.g. -lccom -lcgui -lalleg). ! </ul> ! ! ! @heading ! Contact Info ! ! Email:<ul> ! chr...@md... ! </ul> ! Homepage:<ul> ! http://www.idt.mdh.se/~csg/cgui/cguix ! </ul> ! Telephone:<ul> ! +46.(0)21.38.10.66 ! </ul> Index: ccom._tx =================================================================== RCS file: /cvsroot/ccomx/ccom/docs/ccom._tx,v retrieving revision 1.5 retrieving revision 1.6 diff -C2 -d -r1.5 -r1.6 *** ccom._tx 8 Feb 2004 20:47:21 -0000 1.5 --- ccom._tx 21 Jun 2004 19:17:54 -0000 1.6 *************** *** 1,238 **** ! @#This is the source for the CCOM manual, in Shawn's special format. ! @#The readable documents are generated and will be found in the files: ! @#ccom.txt,ccom.rtf, ccom.htm, ccom.inf, the latter may be ! @#installed as on-line help if you are using rhide (just add cbarcode to the ! @#list of help files) ! @# ! @multiwordheaders ! @manh="version 1.0.0" "CCOM" "Manual" ! @document_title=CCOM Manual ! @rtfh=CCOM - an add on lib to CGUI for accessing the serial ports ! @$\input texinfo ! @$@setfilename ccom.inf ! @$@settitle CCOM Manual ! @$@setchapternewpage odd ! @$@paragraphindent 0 ! @$ ! @$@ifinfo ! @$This is the Info version of the CCOM manual ! @$ ! @$By Christer Sandberg and Rasmus Myklebust ! @$@end ifinfo ! @$ ! @$@node Top, , (dir), (dir) ! @<html> ! @<head> ! @<title>The CCOM API</title> ! @<body> ! <center><b>CCOM</b></center> ! <center><b>A CGUI and Allegro addon Communication package</b></center> ! <center><b>by Christer Sandberg and Rasmus Myklebust</b></center> ! <center>Email: <email>chr...@md...</a></center> ! <center>Homepage: <a href="http://www.idt.mdh.se/~csg/cgui/cguix">http://www.idt.mdh.se/~csg/cgui/cguix</a></center> ! <center><b> ! The Manual of CCOM 1.0.0 ! </b></center> ! @!text ! ! @heading ! Contents ! ! @contents ! ! @text ! @heading ! Using CCOM ! @xref Simple use of COM ports ! @xref Direct_port_setting ! To be able to call the functions in the CCOM lib you must first build and ! install the lib and then #include <ccom.h> in your C file(s). You must ! also link to the lib libcgui.a (or use the dynamic linked module). When ! you run your program you must also ensure that the text labels for the ! dialogue rea present (don't forget this when you distribute your program ! to other people!). You can find that file in the examples directory of ! CCOM. ! ! @heading ! Simple use of COM ports ! @xref Direct_port_setting ! A "serial port" is a chip in the computer with two sides, one "speaking" to ! the CPU (i.e. your program), the other sending data to and receiving data ! from some device connected to the plug at the back of the computer. ! The transmission of data on the line can be done in different manners, ! the sender and receiver must always agree on which manner. The current ! hardware is not able to do anything like "auto-detection". Therefore ! the port must be informed how to transmit data to and from the ! currently connected device. These "port settings" must be set from the "CPU ! side" of the port, i.e. your program must do it. Only the end user of your ! program knows what device that is connected to his or her computer for the ! moment. Therefore the task is quite simple for you: Provide the end-user ! with some kind of dialogue to enter the port settings. When the settings has ! been chosen the port must be informed about these settings. <br> ! The major tasks for CCOM are: ! <ul> ! <li> provide such a dialogue ! <li> hide details about how to tell the port about these settings ! <li> hide details about how to send and receive data ! </ul> ! To send data you just call the send-function. To be able to receive data ! you need to call another function to "register" a call-back (a pointer to ! some function that you have written) that will be called as soon as some ! data has reached the port from the outside world.<br> ! ! @@int @CcomSettingsDialogue(int portnr); ! Starts a dialogue which let the user modify the port settings. If the ! user confirms the changes made (by closing the dialogue with ! "OK"), the new settings will immediately be applied to the hardware and ! also stored into the config-file. <br> ! Parameter: ! <ul> ! <li> portnr: the port number (CCOM_COM1, CCOM_COM2, CCOM_COM3, CCOM_COM4) to ! modify settings for. ! </ul> ! Returns 1 if successful else 0. ! ! @@int @CcomSendBuffer(int portnr, const char *buffer, int n, void (*Notify) (int portnr, void *data), void *data); ! Starts the sending of the buffer `buffer' to port `portnr'. ! If the previous buffer(s) has not yet been sent, `CcomSendBuffer' will ! enque the new buffer. The first time ! `CcomStartScanning' or `CcomSendBuffer' is called for a certain port the ! port settings will be loaded from the current config file.<br> ! <ul> ! <li> portnr: The port number (CCOM_COM*) to send the buffer to ! <li> buffer: The data to send. A copy of `buffer' will be made so ! you are free to destroy your calling buffer. ! <li> n: The number of bytes to send. ! <li> Notify: (optional) A pointer to a function of yours, that will ! be called when the buffer has been successfully sent. If you don't ! need any notification, just pass NULL.<br> ! `Notify' is associated with the current buffer only so, if you want, ! you may alter both the call-back and data-pointer between different ! buffers. ! Parameters to `Notify': ! <ul> ! <li> portnr: The port that the data was sent on. ! <li> data: The pointer `data' passed to `CcomSendBuffer'. ! </ul> ! <li> data: A pointer to some data that will be passed to `Notify', pass ! NULL if you don't need it. ! </ul> ! Returns 1 if successful else 0. ! ! @@int @CcomStartScanning(int portnr, int options, void (*CallBack) (int portnr, int readdata, int error, void *data), void *data); ! Starts to check the port `portno' for bytes. The first time ! `CcomStartScanning' or `CcomSendBuffer' is called for a certain port the ! port settings will be loaded from the current config file. ! <ul> ! <li> portnr: The port number (CCOM_COM*) to receive bytes from. ! <li> CallBack: A pointer to a function of yours that will ! be called as soon as a byte has been received. <br> ! Parameters to `CallBack': ! <ul> ! <li> portnr: The port where the data was received ! <li> options: Currently not used. ! <li> readdata: The the low-order byte of `readdata' contains ! the byte read from the port. ! <li> error: If a transmission error was detected, then this ! error code will be passed in `error'. The possible errors are: ! <ul> ! <li> CCOM_ERR_ORUN - Overrun, may occure if polling is used and ! the progam is not fast enough to check the port. ! <li> CCOM_ERR_PAR - Parity error, may occure if there is a bad ! line or the port settings is not the same on receiving ! computer and the sending device. ! <li> CCOM_ERR_FRAME - Frame error, may occure if there is a bad ! line or the port settings is not the same on receiving ! computer and the sending device. ! </ul> ! <li> data: The pointer `data' passed to `CcomStartScanning'. ! </ul> ! <li> data: A pointer to some data that will be passed to `CallBack', pass ! NULL if you don't need it. ! </ul> ! Returns 1 if successful else 0. ! ! @@int @CcomStopSending(int portno) ! Normally you don't need to use this function. `CcomStopSending' will stop ! the sending. Buffers that are unsent (partially or completetly) ! will be dropped. ! Returns 1 if successful else 0. ! ! @@int @CcomStopScanning(int portno); ! Normally you don't need to use this function. `CcomStopScanning' will stop ! scanning (checking the port for incoming data). ! Returns 1 if successful else 0. ! ! @@void @CcomSetPath(const char *path); ! It's not necessary to use this function. The dialogue will look for the ! file with textlabels in the current directory (i.e. it will try to open ! "ccomlabl.txt"). I you prefere locating that file somewhere else you can ! can use `CcomSetPath' to specify that path. The path must include also the ! file name. The path may lead to somewhere in a datafile if you use the ! '#' delimiter after the data-file name (as usual). ! In the distribution of CCOM the text-file is located in the examples ! directory. It can be re-built by use of the `mktext' tool of CGUI (see ! the tools directory of CGUI for details about the tool). Enter the ! command `make texts CGUIDIR=<path>' where <path> is the path to your ! CGUI directory. To add labels of your favorite language to the label file ! do these additions into file src/*.t and re-build. If you do it, it would ! also be fine if you send me the changes so I can add them to next release! ! ! @heading ! Direct_port_setting ! @xref Simple use of COM ports ! If you for some reason don't like the dialogue for port settings, you can ! make your own and instead use the direct port setting functions.<br> ! In some cases you may want to do a program for computer-computer ! communication, then it may in some cases be meaningful to hard-code the ! port settings, in which case the direct port setting functions can be used. ! In most cases it will however not be meaningful to hard-code the settings of ! the port. ! ! @@int @CcomSetBaud(int portno, long baud_rate); ! Normally you dont need to call this function. ! Modifies the port setting concerning the transmission speed. If you call ! this function you must call it after the first call to `CcomStartScanning' ! or `CcomSendBuffer'. ! Returns 1 if successful else 0. ! ! @@int @CcomSetBits(int portno, int nrbits); ! Normally you dont need to call this function. ! Modifies the port setting concerning number of bits in each byte. `nrbits' ! can range from 5 to 8. If you use this function you must call it after ! the first call to `CcomStartScanning' or `CcomSendBuffer'. ! Returns 1 if successful else 0. ! ! @@int @CcomSetStopBits(int portno, int stopbits); ! Normally you dont need to call this function. ! Modifies the port setting concerning stopbits. `stopbits' can be either 1 ! or 2. If you use this function you must call it after the first call ! to `CcomStartScanning' or `CcomSendBuffer'. ! Returns 1 if successful else 0. ! ! @@int @CcomSetParity(int portno, int parity); ! Normally you dont need to call this function. ! Modifies the port setting concerning parity. If `parity' is ! 1 the parity check will be "even", if 0 odd. If you use this function ! you must call it after the first call to `CcomStartScanning' or ! `CcomSendBuffer'. ! Returns 1 if successful else 0. ! ! @@int @CcomSetParityEnable(int portno, int parityenable); ! Normally you dont need to call this function. ! Modifies the port setting concerning parity enable. If `parityenable' is ! 1 the parity check will be enabled, if 0 disabled. If you use this ! function you must call it after the first call to `CcomStartScanning' or ! `CcomSendBuffer'. ! Returns 1 if successful else 0. ! ! @headingnocontent ! Index ! ! @index ! ! @$@contents ! @$@bye ! ! @html ! @text --- 1,238 ---- ! @#This is the source for the CCOM manual, in Shawn's special format. ! @#The readable documents are generated and will be found in the files: ! @#ccom.txt,ccom.rtf, ccom.htm, ccom.inf, the latter may be ! @#installed as on-line help if you are using rhide (just add cbarcode to the ! @#list of help files) ! @# ! @multiwordheaders ! @manh="version 0.9.2" "CCOM" "Manual" ! @document_title=CCOM Manual ! @rtfh=CCOM - an add on lib to CGUI for accessing the serial ports ! @$\input texinfo ! @$@setfilename ccom.inf ! @$@settitle CCOM Manual ! @$@setchapternewpage odd ! @$@paragraphindent 0 ! @$ ! @$@ifinfo ! @$This is the Info version of the CCOM manual ! @$ ! @$By Christer Sandberg and Rasmus Myklebust ! @$@end ifinfo ! @$ ! @$@node Top, , (dir), (dir) ! @<html> ! @<head> ! @<title>The CCOM API</title> ! @<body> ! <center><b>CCOM</b></center> ! <center><b>A CGUI and Allegro addon Communication package</b></center> ! <center><b>by Christer Sandberg and Rasmus Myklebust</b></center> ! <center>Email: <email>chr...@md...</a></center> ! <center>Homepage: <a href="http://www.idt.mdh.se/~csg/cgui/cguix">http://www.idt.mdh.se/~csg/cgui/cguix</a></center> ! <center><b> ! The Manual of CCOM 0.9.2 ! </b></center> ! @!text ! ! @heading ! Contents ! ! @contents ! ! @text ! @heading ! Using CCOM ! @xref Simple use of COM ports ! @xref Direct_port_setting ! To be able to call the functions in the CCOM lib you must first build and ! install the lib and then #include <ccom.h> in your C file(s). You must ! also link to the lib libcgui.a (or use the dynamic linked module). When ! you run your program you must also ensure that the text labels for the ! dialogue rea present (don't forget this when you distribute your program ! to other people!). You can find that file in the examples directory of ! CCOM. ! ! @heading ! Simple use of COM ports ! @xref Direct_port_setting ! A "serial port" is a chip in the computer with two sides, one "speaking" to ! the CPU (i.e. your program), the other sending data to and receiving data ! from some device connected to the plug at the back of the computer. ! The transmission of data on the line can be done in different manners, ! the sender and receiver must always agree on which manner. The current ! hardware is not able to do anything like "auto-detection". Therefore ! the port must be informed how to transmit data to and from the ! currently connected device. These "port settings" must be set from the "CPU ! side" of the port, i.e. your program must do it. Only the end user of your ! program knows what device that is connected to his or her computer for the ! moment. Therefore the task is quite simple for you: Provide the end-user ! with some kind of dialogue to enter the port settings. When the settings has ! been chosen the port must be informed about these settings. <br> ! The major tasks for CCOM are: ! <ul> ! <li> provide such a dialogue ! <li> hide details about how to tell the port about these settings ! <li> hide details about how to send and receive data ! </ul> ! To send data you just call the send-function. To be able to receive data ! you need to call another function to "register" a call-back (a pointer to ! some function that you have written) that will be called as soon as some ! data has reached the port from the outside world.<br> ! ! @@int @CcomSettingsDialogue(int portnr); ! Starts a dialogue which let the user modify the port settings. If the ! user confirms the changes made (by closing the dialogue with ! "OK"), the new settings will immediately be applied to the hardware and ! also stored into the config-file. <br> ! Parameter: ! <ul> ! <li> portnr: the port number (CCOM_COM1, CCOM_COM2, CCOM_COM3, CCOM_COM4) to ! modify settings for. ! </ul> ! Returns 1 if successful else 0. ! ! @@int @CcomSendBuffer(int portnr, const char *buffer, int n, void (*Notify) (int portnr, void *data), void *data); ! Starts the sending of the buffer `buffer' to port `portnr'. ! If the previous buffer(s) has not yet been sent, `CcomSendBuffer' will ! enque the new buffer. The first time ! `CcomStartScanning' or `CcomSendBuffer' is called for a certain port the ! port settings will be loaded from the current config file.<br> ! <ul> ! <li> portnr: The port number (CCOM_COM*) to send the buffer to ! <li> buffer: The data to send. A copy of `buffer' will be made so ! you are free to destroy your calling buffer. ! <li> n: The number of bytes to send. ! <li> Notify: (optional) A pointer to a function of yours, that will ! be called when the buffer has been successfully sent. If you don't ! need any notification, just pass NULL.<br> ! `Notify' is associated with the current buffer only so, if you want, ! you may alter both the call-back and data-pointer between different ! buffers. ! Parameters to `Notify': ! <ul> ! <li> portnr: The port that the data was sent on. ! <li> data: The pointer `data' passed to `CcomSendBuffer'. ! </ul> ! <li> data: A pointer to some data that will be passed to `Notify', pass ! NULL if you don't need it. ! </ul> ! Returns 1 if successful else 0. ! ! @@int @CcomStartScanning(int portnr, int options, void (*CallBack) (int portnr, int readdata, int error, void *data), void *data); ! Starts to check the port `portno' for bytes. The first time ! `CcomStartScanning' or `CcomSendBuffer' is called for a certain port the ! port settings will be loaded from the current config file. ! <ul> ! <li> portnr: The port number (CCOM_COM*) to receive bytes from. ! <li> CallBack: A pointer to a function of yours that will ! be called as soon as a byte has been received. <br> ! Parameters to `CallBack': ! <ul> ! <li> portnr: The port where the data was received ! <li> options: Currently not used. ! <li> readdata: The the low-order byte of `readdata' contains ! the byte read from the port. ! <li> error: If a transmission error was detected, then this ! error code will be passed in `error'. The possible errors are: ! <ul> ! <li> CCOM_ERR_ORUN - Overrun, may occure if polling is used and ! the progam is not fast enough to check the port. ! <li> CCOM_ERR_PAR - Parity error, may occure if there is a bad ! line or the port settings is not the same on receiving ! computer and the sending device. ! <li> CCOM_ERR_FRAME - Frame error, may occure if there is a bad ! line or the port settings is not the same on receiving ! computer and the sending device. ! </ul> ! <li> data: The pointer `data' passed to `CcomStartScanning'. ! </ul> ! <li> data: A pointer to some data that will be passed to `CallBack', pass ! NULL if you don't need it. ! </ul> ! Returns 1 if successful else 0. ! ! @@int @CcomStopSending(int portno) ! Normally you don't need to use this function. `CcomStopSending' will stop ! the sending. Buffers that are unsent (partially or completetly) ! will be dropped. ! Returns 1 if successful else 0. ! ! @@int @CcomStopScanning(int portno); ! Normally you don't need to use this function. `CcomStopScanning' will stop ! scanning (checking the port for incoming data). ! Returns 1 if successful else 0. ! ! @@void @CcomSetPath(const char *path); ! It's not necessary to use this function. The dialogue will look for the ! file with textlabels in the current directory (i.e. it will try to open ! "ccomlabl.txt"). I you prefere locating that file somewhere else you can ! can use `CcomSetPath' to specify that path. The path must include also the ! file name. The path may lead to somewhere in a datafile if you use the ! '#' delimiter after the data-file name (as usual). ! In the distribution of CCOM the text-file is located in the examples ! directory. It can be re-built by use of the `mktext' tool of CGUI (see ! the tools directory of CGUI for details about the tool). Enter the ! command `make texts CGUIDIR=<path>' where <path> is the path to your ! CGUI directory. To add labels of your favorite language to the label file ! do these additions into file src/*.t and re-build. If you do it, it would ! also be fine if you send me the changes so I can add them to next release! ! ! @heading ! Direct_port_setting ! @xref Simple use of COM ports ! If you for some reason don't like the dialogue for port settings, you can ! make your own and instead use the direct port setting functions.<br> ! In some cases you may want to do a program for computer-computer ! communication, then it may in some cases be meaningful to hard-code the ! port settings, in which case the direct port setting functions can be used. ! In most cases it will however not be meaningful to hard-code the settings of ! the port. ! ! @@int @CcomSetBaud(int portno, long baud_rate); ! Normally you dont need to call this function. ! Modifies the port setting concerning the transmission speed. If you call ! this function you must call it after the first call to `CcomStartScanning' ! or `CcomSendBuffer'. ! Returns 1 if successful else 0. ! ! @@int @CcomSetBits(int portno, int nrbits); ! Normally you dont need to call this function. ! Modifies the port setting concerning number of bits in each byte. `nrbits' ! can range from 5 to 8. If you use this function you must call it after ! the first call to `CcomStartScanning' or `CcomSendBuffer'. ! Returns 1 if successful else 0. ! ! @@int @CcomSetStopBits(int portno, int stopbits); ! Normally you dont need to call this function. ! Modifies the port setting concerning stopbits. `stopbits' can be either 1 ! or 2. If you use this function you must call it after the first call ! to `CcomStartScanning' or `CcomSendBuffer'. ! Returns 1 if successful else 0. ! ! @@int @CcomSetParity(int portno, int parity); ! Normally you dont need to call this function. ! Modifies the port setting concerning parity. If `parity' is ! 1 the parity check will be "even", if 0 odd. If you use this function ! you must call it after the first call to `CcomStartScanning' or ! `CcomSendBuffer'. ! Returns 1 if successful else 0. ! ! @@int @CcomSetParityEnable(int portno, int parityenable); ! Normally you dont need to call this function. ! Modifies the port setting concerning parity enable. If `parityenable' is ! 1 the parity check will be enabled, if 0 disabled. If you use this ! function you must call it after the first call to `CcomStartScanning' or ! `CcomSendBuffer'. ! Returns 1 if successful else 0. ! ! @headingnocontent ! Index ! ! @index ! ! @$@contents ! @$@bye ! ! @html ! @text |
