/*	
 *	clipcom.h
 *
 *	調歩同期シリアル通信ドライバ
 *
 *	CLiP - Common Library for P/ECE
 *	Copyright (C) 2001-2004 Naoyuki Sawa
 *
 *	* Mon May 17 22:46:00 JST 2004 Naoyuki Sawa
 *	- 作成開始。
 */
#ifndef __CLIP_COM_H__
#define __CLIP_COM_H__

/****************************************************************************
 *	ハードウェア仕様
 ****************************************************************************/

/* =============
 * P/ECE拡張端子
 * =============
 *
 *	----	----	----
 *	端子	機能	用途
 *	----	----	----
 *	1	P14	#CTS
 *	2	GND	GND
 *	3	DSIO	結線しません
 *	4	P12	#RTS
 *	5	Vcc	Vcc
 *	6	P06	結線しません
 *	7	SOUT1	TxD
 *	8	SIN1	RxD
 *
 *	拡張端子にシリアル通信機器を接続せずにCOMポートを開くと、
 *	入力端子状態が不安定になって受信割り込みと受信エラー割り込みが頻発し、
 *	ハングアップしてしまう場合があるようです。
 */

/****************************************************************************
 *	
 ****************************************************************************/

/* COMポートを開きます。
 * [in]
 *	baudrate	転送速度(ビット/秒)
 *	parity		0:パリティなし or 1:奇数パリティ or 2:偶数パリティ
 *	bytesize	7:7ビット or 8:8ビット
 *	stopbits	1:1ビット or 2:2ビット
 *	rxbuf_size	送信バッファサイズ(バイト)。0を指定すると、規定サイズを使います。
 *	txbuf_size	送信バッファサイズ(バイト)。0を指定すると、規定サイズを使います。
 *	recv_callback	受信通知コールバックを指定します。NULLならばコールバックしません。
 *	send_callback	送信完了コールバックを指定します。NULLならばコールバックしません。
 * [note]
 *	* 既にCOMポートが開かれていた場合は、いったん閉じた後、新しい設定で開きなおします。
 *	* com_open()を呼んだアプリケーションは、終了する前に必ずcom_close()を呼んでください。
 *	  CLiPライブラリの終了ルーチンは自動的にcom_close()を呼びません。
 *	* com_open()直後の初期状態で、RTS信号は1(データ受信可能)となっています。
 *	  通常は、このままでデータ送受信が可能です。
 *	  明示的なハードウェアフロー制御を行う場合は、必要に応じてcom_rts()関数を使ってください。
 *	* 受信通知コールバックは、次の条件で呼び出されます。
 *	  1. 新たなデータを1バイト受信したとき。
 *	  2. 受信エラーが発生したとき。
 *	* 送信完了コールバックは、次の条件で呼び出されます。
 *	  1. シリアルI/Fの送信バッファが空で、かつ、ドライバの送信バッファも空のとき。
 *	  ※2004/05/31現在の実装では、必ずしも送信完了タイミングでのみコールバックするわけではありません。
 *	    シリアルI/Fとドライバの送信バッファがどちらも空である任意のタイミングで、コールバックする可能性があります。
 *	    あまり使いみちはないかも知れません・・・
 */
void com_open(int baudrate, int parity, int bytesize, int stopbits, int rxbuf_size, int txbuf_size, void (*recv_callback)(), void (*send_callback)());

/* COMポートを閉じます。
 * [note]
 *	* COMポートが開かれていない場合は、何もせずに処理を返します。
 */
void com_close();

/* データを受信します。
 * [in]
 *	buf		受信データを受け取るためのバッファの先頭アドレス。
 *	maxlen		受信データを受け取るためのバッファのバイト数。
 * [out]
 *	戻り値		- 受信データのバイト数。
 *			  戻り値がmaxlenを超えることはありません。
 *			- 受信エラーが発生した場合は、-1を返します。
 *			  いったん受信エラーが発生すると、com_reset()を呼ぶまで-1を返し続けます。
 */
int com_recv(void* buf, int maxlen);

/* データを送信します。
 * [in]
 *	buf		送信データの先頭アドレス。
 *	len		送信データのバイト数。
 *			-1を指定すると、AsciiZ文字列と見なしてデータサイズを自動判断します。
 * [out]
 *	戻り値		- 送信データのバイト数。
 *			  引数lenと同じ値、または引数lenに-1を指定した場合は文字列長を返します。
 *			- 送信エラーが発生した場合は、-1を返します。
 *			  2004/05/18現在の実装では、com_send()関数がエラーを返すことはありません。
 *			  今後、フロー制御や送信タイムアウト処理を追加した場合に利用する予定です。
 * [note]
 *	* 送信バッファに空きがない場合、送信バッファに空きができるまで、関数内部にてブロックします。
 *	  2004/05/18現在の実装では、ドライバ構造体の送信バッファオーバーフローは絶対に発生しません。
 */
int com_send(const void* buf, int len);

/* シリアル通信ドライバをリセットします。
 * [note]
 *	* 受信バッファをクリアし、受信エラーをリセットします。
 *	* 送信バッファをクリアします。
 */
void com_reset();

/* RTS信号を設定します。
 * [in]
 *	value		1:P/ECEがデータ受信可能であることを、接続機器に対して通知する。(+12V)
 *			0:P/ECEがデータ受信不可であることを、接続機器に対して通知する。(-12V)
 */
void com_rts(int value);

/* CTS信号を取得します。
 * [out]
 *	戻り値		1:接続機器がデータ受信可能であることを、P/ECEに対して通知している。(+12V)
 *			0:接続機器がデータ受信不可であることを、P/ECEに対して通知している。(-12V)
 */
int com_cts();

#endif /*__CLIP_COM_H__*/
