updated API and documentation. Now we use the gnome way for creating

API docs.

3 files changed, 10 insertions, 196 deletions

diff --git a/doc/API b/doc/API
deleted file mode 100644
index ff1ddd76c5..0000000000
--- a/doc/API
+++ /dev/null
@@ -1,194 +0,0 @@
-This may not be complete yet. Check at gnutls.h for current information.
-
-All functions return >=0 if everything is ok, or a negative value in case
-of a failure. Failure is not always fatal.
-
-int gnutls_init(GNUTLS_STATE * state, ConnectionEnd con_end);
-	This function just initializes a gnutls state to null.
-	con_end can be either GNUTLS_CLIENT or GNUTLS_SERVER. 
-
-int gnutls_deinit(GNUTLS_STATE state);
-	This function clears all buffers associated with the state.
-	
-int gnutls_handshake(int cd, GNUTLS_STATE state);
-	This function does the handshake of the TLS/SSL protocol,
-	and initializes the TLS connection.
-	It accepts a TCP connection descriptor and a GNUTLS state.
-	This function will fail if any problem is encountered,
-	and the connection should be terminated.
-
-int gnutls_handshake_begin(int cd, GNUTLS_STATE state);
-	This function does the handshake of the TLS/SSL protocol.
-	This function will fail if any problem is encountered.
-	However this failure will not be fatal. You may choose to
-	continue the handshake - eg. even if the certificate cannot
-	be verified- by calling gnutls_handshake_finish()
-
-int gnutls_handshake_finish(int cd, GNUTLS_STATE state);
-	This function does the final stuff of the handshake protocol.
-	This function will fail if any problem is encountered.
-
-int gnutls_close(int cd, GNUTLS_STATE state);
-	Terminates the current TLS/SSL connection. If it returns 0
-	you may continue using the TCP connection.
-
-int gnutls_send_hello_request(int cd, GNUTLS_STATE state);
-	This function will renegotiate security parameters with the
-	client. This should only be called in case of a server.
-	If the client does not wish to renegotiate parameters he
-	will reply with an alert message, thus the return code will be
-	GNUTLS_E_WARNING_ALERT_RECEIVED and the alert will be
-	GNUTLS_NO_RENEGOTIATION.
-
-AlertDescription gnutls_get_last_alert( GNUTLS_STATE state);
-	Returns the last alert number received. This function
-	should be called if GNUTLS_E_WARNING_ALERT_RECEIVED or
-	GNUTLS_E_FATAL_ALERT_RECEIVED has been returned by a gnutls 
-	function.
-	The peer may send alerts if he thinks some things were not
-	right. Check gnutls.h for the available alert descriptions.
-
-KXAlgorithm gnutls_get_current_kx( GNUTLS_STATE state);
-	Returns the key exchange algorithm used in the first key exchange.
-	(There is not key exchange in resumed sessions).
-
-BulkCipherAlgorithm gnutls_get_current_cipher( GNUTLS_STATE state);
-	Returns the currently used cipher.
-
-char *_gnutls_cipher_get_name(BulkCipherAlgorithm);
-	Returns a malloc'ed string with the name of the algorithm;
-
-MACAlgorithm gnutls_get_current_mac_algorithm( GNUTLS_STATE state);
-	Returns the mac algorithm used.
-
-char *_gnutls_mac_get_name(MACAlgorithm);
-	Returns a malloc'ed string with the name of the algorithm;
-
-CompressionMethod gnutls_get_current_compression_method( GNUTLS_STATE state);
-	Returns the compression algorithm used.
-
-char *_gnutls_compression_get_name(CompressionMethod);
-	Returns a malloc'ed string with the name of the algorithm;
-
-int gnutls_is_fatal_error( int error);
-	If a function returns a negative value you may feed that value
-	to this function to see if it is fatal. Returns 1 for a fatal
-	error 0 otherwise. However you may want to check the
-	error code manual, since some non-fatal errors to the protocol
-	may be fatal for you (your program).
-
-void gnutls_perror( int error);
-char* gnutls_strerror( int error);
-	These funtions are like perror() and strerror().
-	gnutls_strerror() returns a malloc'ed value thus it must be
-	freed.
-
-ssize_t gnutls_write(int cd, GNUTLS_STATE state, void* data, int sizeofdata);
-	This function has the same semantics as write() has. The only
-	difference is that is accepts a GNUTLS state.
-	
-ssize_t gnutls_read(int cd, GNUTLS_STATE state, void* data, int sizeofdata);
-	This function has the same semantics as read() has. The only
-	difference is that is accepts a GNUTLS state.
-
-ssize_t gnutls_recv(int cd, GNUTLS_STATE state, void* data, int sizeofdata, int flags);
-	This function has the same semantics as recv() has. The only
-	difference is that is accepts a GNUTLS state. Flags are the flags
-	passed to recv() and should be used with care in gnutls. 
-	The only acceptable flag is currently MSG_DONTWAIT. In that case, 
-	if the socket is set to non blocking IO it will return GNUTLS_E_AGAIN,
-	if there are no data in the socket. 
-
-ssize_t gnutls_send(int cd, GNUTLS_STATE state, void* data, int sizeofdata, int flags);
-	This function has the same semantics as send() has. The only
-	difference is that is accepts a GNUTLS state. Currently flags cannot
-	be anything except 0.
-
-int gnutls_check_pending( GNUTLS_STATE state);
-	This function checks if there are any data to receive 
-	in the gnutls buffers. Returns the size of that data or 0.
-	Notice that you may also use select() to check for data in
-	the TCP connection, instead of this function.
-	(gnutls leaves some data in the tcp buffer in order for select
-	to work).
-
-void gnutls_set_cipher_priority( GNUTLS_STATE state, ...);
-	Sets the priority on the ciphers supported by gnutls.
-	Priority is higher for ciphers specified before others.
-	After specifying the ciphers you want, you should add 0.
-	Note that the priority is set on the client. The server does
-	not use the algorithm's priority except for disabling 
-	algorithms that were not specified.
-
-int gnutls_set_kx_cred( GNUTLS_STATE state, int kx, void* cred);
-	Sets the needed credentials for the specified (in kx) authentication
-	algorithm. Eg username, password - or public and private keys etc.
-	The (void* cred) parameter is a structure that depends on the
-	specified kx algorithm and on the current state (client or server).
-	[ In order to minimize memory usage, and share credentials between
-	several threads gnutls keeps a pointer to cred, and not the whole cred 
-	structure. Thus you will have to keep the structure allocated until
-	you call gnutls_deinit(). ]
-
-	* For GNUTLS_KX_DH_ANON cred should be NULL in case of a client.
-	 In case of a server it should be DH_ANON_SERVER_CREDENTIALS.
-	* For GNUTLS_KX_SRP cred should be SRP_CLIENT_CREDENTIALS
- 	 in case of a client, and SRP_SERVER_CREDENTIALS, in case
-	 of a server.
-
-void* gnutls_get_auth_info( GNUTLS_STATE state);
-	Must be called after a complete gnutls_handshake().
-	Returns a pointer to authentication information.
-	* For GNUTLS_KX_ANON returns a pointer to DH_ANON_AUTH_INFO;
-	* For GNUTLS_KX_SRP returns a pointer to structure SRP_AUTH_INFO.
-	 (you should not free that). Thus you can access the 
-         username he used to connect.
-
-void gnutls_set_kx_priority( GNUTLS_STATE state, ...);
-	like gnutls_set_cipher_priority, but for key exchange methods.
-
-void gnutls_set_mac_priority( GNUTLS_STATE state, ...);
-	like gnutls_set_cipher_priority, but for mac algorithms.
-
-void gnutls_set_compression_priority( GNUTLS_STATE state, ...);
-	like gnutls_set_cipher_priority, but for compression algorithms.
-
-void gnutls_set_current_version(GNUTLS_STATE state, GNUTLS_Version version); 
-	Sets the current SSL/TLS version. Accepted values are GNUTLS_SSL3
-	and GNUTLS_TLS1.
-
-int gnutls_get_current_session_id( GNUTLS_STATE state, void* session, int *session_size);
-	Returns the session id. This can be used if you want to check if 
-	the next session you tried to resume was actually resumed.
-	(resumed sessions have the same sessionID with the first session)
-
-int gnutls_get_current_session( GNUTLS_STATE state, void* session, int *session_size);
-	Returns all session parameters - in order to support resuming.
-	The client should call this - and keep the returned session - if he wants to
-	resume that current version later by calling gnutls_set_current_session().
-	This function must be called after a successful handshake.
-
-int gnutls_set_current_session( GNUTLS_STATE state, void* session, int session_size);
-	Sets all session parameters - in order to support resuming 
-	session must be the one returned by get_current_session();
-	This function should be called before gnutls_handshake_begin.
-	Keep in mind that session resuming is advisory. The server may
-	choose not to resume the session, thus a full handshake will be
-	performed.
-
-int gnutls_set_lowat( GNUTLS_STATE state, int num);
-	Used to set the lowat value in order for select to check
-	if there are pending data to socket buffer. Used only
-	if you have changed the default low water value (default is 1).
-	Normally you will not need that function.
-
-int gnutls_set_cache_expiration( GNUTLS_STATE state, int seconds);
-	Sets the expiration time for resumed sessions.
-
-int gnutls_set_db_name( GNUTLS_STATE state, char* filename);
-	Sets the name of the (gdbm) database to be used to keep
-        the sessions to be resumed.
-
-int gnutls_clean_db( GNUTLS_STATE state);
-	Deletes all expired records in the db. This db may become huge
-	if this is not called.
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 0aae5e3186..9840929f62 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1 +1,10 @@
-EXTRA_DIST = TODO API
+EXTRA_DIST = TODO gnutls.3 gnutls-api.txt gnutls-api.html
+man_MANS = gnutls.3
+
+gnutls.3: 
+	@gdoc -man ../lib/*.c > gnutls.3
+gnutls-api: gnutls-api.html gnutls-api.txt
+gnutls-api.html: 
+	@gdoc -man ../lib/*.c > gnutls-api.html
+gnutls-api.txt:
+	@gdoc -text ../lib/*.c > gnutls-api.txt
diff --git a/doc/TODO b/doc/TODO
index ae8b335918..638cff1880 100644
--- a/doc/TODO
+++ b/doc/TODO
@@ -1,5 +1,4 @@
 * x509 Certificate API ( Fabio.Fiorina@alcatel.it is currently working on an ASN.1 parser)
 * OpenPGP certificate support (through libgcrypt)
-* Document API using texi (any volunteers?)
 * Add Kerberos support (who wants that?)
 * Audit the code (volunteers?)