From 9e8a131169e82446705ce3bd32c49aef6aefb4c5 Mon Sep 17 00:00:00 2001 From: Simon Josefsson Date: Wed, 14 Nov 2007 17:44:53 +0100 Subject: Doc fix. --- lib/gnutls_state.c | 150 ++++++++++++++++++++++++++--------------------------- 1 file changed, 75 insertions(+), 75 deletions(-) diff --git a/lib/gnutls_state.c b/lib/gnutls_state.c index dee644d4be..f1d64917c6 100644 --- a/lib/gnutls_state.c +++ b/lib/gnutls_state.c @@ -55,7 +55,7 @@ _gnutls_session_cert_type_set (gnutls_session_t session, * gnutls_cipher_get - Returns the currently used cipher. * @session: is a #gnutls_session_t structure. * - * Returns the currently used cipher. + * Returns: the currently used cipher. **/ gnutls_cipher_algorithm_t gnutls_cipher_get (gnutls_session_t session) @@ -67,9 +67,11 @@ gnutls_cipher_get (gnutls_session_t session) * gnutls_certificate_type_get - Returns the currently used certificate type. * @session: is a #gnutls_session_t structure. * - * Returns the currently used certificate type. The certificate type - * is by default X.509, unless it is negotiated as a TLS extension. + * The certificate type is by default X.509, unless it is negotiated + * as a TLS extension. * + * Returns: the currently used %gnutls_certificate_type_t certificate + * type. **/ gnutls_certificate_type_t gnutls_certificate_type_get (gnutls_session_t session) @@ -81,7 +83,7 @@ gnutls_certificate_type_get (gnutls_session_t session) * gnutls_kx_get - Returns the key exchange algorithm. * @session: is a #gnutls_session_t structure. * - * Returns the key exchange algorithm used in the last handshake. + * Returns: the key exchange algorithm used in the last handshake. **/ gnutls_kx_algorithm_t gnutls_kx_get (gnutls_session_t session) @@ -93,7 +95,7 @@ gnutls_kx_get (gnutls_session_t session) * gnutls_mac_get - Returns the currently used mac algorithm. * @session: is a #gnutls_session_t structure. * - * Returns the currently used mac algorithm. + * Returns: the currently used mac algorithm. **/ gnutls_mac_algorithm_t gnutls_mac_get (gnutls_session_t session) @@ -105,7 +107,7 @@ gnutls_mac_get (gnutls_session_t session) * gnutls_compression_get - Returns the currently used compression algorithm. * @session: is a #gnutls_session_t structure. * - * Returns the currently used compression method. + * Returns: the currently used compression method. **/ gnutls_compression_method_t gnutls_compression_get (gnutls_session_t session) @@ -214,14 +216,17 @@ _gnutls_handshake_internal_state_clear (gnutls_session_t session) #define MIN_DH_BITS 727 /** * gnutls_init - This function initializes the session to null (null encryption etc...). - * @con_end: is used to indicate if this session is to be used for server or - * client. Can be one of GNUTLS_CLIENT and GNUTLS_SERVER. + * @con_end: indicate if this session is to be used for server or client. * @session: is a pointer to a #gnutls_session_t structure. * - * This function initializes the current session to null. Every session - * must be initialized before use, so internal structures can be allocated. - * This function allocates structures which can only be free'd - * by calling gnutls_deinit(). Returns zero on success. + * This function initializes the current session to null. Every + * session must be initialized before use, so internal structures can + * be allocated. This function allocates structures which can only + * be free'd by calling gnutls_deinit(). Returns zero on success. + * + * @con_end can be one of %GNUTLS_CLIENT and %GNUTLS_SERVER. + * + * Returns: %GNUTLS_E_SUCCESS on success, or an error code. **/ int gnutls_init (gnutls_session_t * session, gnutls_connection_end_t con_end) @@ -327,9 +332,8 @@ _gnutls_session_is_resumable (gnutls_session_t session) * @session: is a #gnutls_session_t structure. * * This function clears all buffers associated with the @session. - * This function will also remove session data from the session database - * if the session was terminated abnormally. - * + * This function will also remove session data from the session + * database if the session was terminated abnormally. **/ void gnutls_deinit (gnutls_session_t session) @@ -622,11 +626,10 @@ _gnutls_dh_set_group (gnutls_session_t session, mpi_t gen, mpi_t prime) * @session: is a pointer to a #gnutls_session_t structure. * @status: is one of GNUTLS_OPENPGP_CERT, or GNUTLS_OPENPGP_CERT_FINGERPRINT * - * This function will order gnutls to send the key fingerprint instead - * of the key in the initial handshake procedure. This should be used - * with care and only when there is indication or knowledge that the - * server can obtain the client's key. - * + * This function will order gnutls to send the key fingerprint + * instead of the key in the initial handshake procedure. This should + * be used with care and only when there is indication or knowledge + * that the server can obtain the client's key. **/ void gnutls_openpgp_send_cert (gnutls_session_t session, @@ -640,14 +643,14 @@ gnutls_openpgp_send_cert (gnutls_session_t session, * @session: is a pointer to a #gnutls_session_t structure. * @status: is 0 or 1 * - * If status is non zero, this function will order gnutls not to send the rdnSequence - * in the certificate request message. That is the server will not advertize - * it's trusted CAs to the peer. If status is zero then the default behaviour will - * take effect, which is to advertize the server's trusted CAs. - * - * This function has no effect in clients, and in authentication methods other than - * certificate with X.509 certificates. + * If status is non zero, this function will order gnutls not to send + * the rdnSequence in the certificate request message. That is the + * server will not advertize it's trusted CAs to the peer. If status + * is zero then the default behaviour will take effect, which is to + * advertize the server's trusted CAs. * + * This function has no effect in clients, and in authentication + * methods other than certificate with X.509 certificates. **/ void gnutls_certificate_send_x509_rdn_sequence (gnutls_session_t session, @@ -686,18 +689,16 @@ _gnutls_record_set_default_version (gnutls_session_t session, * @session: is a #gnutls_session_t structure. * @allow: is an integer (0 or 1) * - * This function will enable or disable the use of private - * cipher suites (the ones that start with 0xFF). By default - * or if @allow is 0 then these cipher suites will not be - * advertized nor used. + * This function will enable or disable the use of private cipher + * suites (the ones that start with 0xFF). By default or if @allow + * is 0 then these cipher suites will not be advertized nor used. * * Unless this function is called with the option to allow (1), then - * no compression algorithms, like LZO. That is because these algorithms - * are not yet defined in any RFC or even internet draft. - * - * Enabling the private ciphersuites when talking to other than gnutls - * servers and clients may cause interoperability problems. + * no compression algorithms, like LZO. That is because these + * algorithms are not yet defined in any RFC or even internet draft. * + * Enabling the private ciphersuites when talking to other than + * gnutls servers and clients may cause interoperability problems. **/ void gnutls_handshake_set_private_extensions (gnutls_session_t session, int allow) @@ -935,7 +936,7 @@ _gnutls_PRF (gnutls_session_t session, * client and server random fields directly, and is recommended if you * want to generate pseudo random data unique for each session. * - * Return value: Return 0 on success, or an error code. + * Returns: %GNUTLS_E_SUCCESS on success, or an error code. **/ int gnutls_prf_raw (gnutls_session_t session, @@ -981,7 +982,7 @@ gnutls_prf_raw (gnutls_session_t session, * * The output is placed in *@OUT, which must be pre-allocated. * - * Return value: Return 0 on success, or an error code. + * Returns: %GNUTLS_E_SUCCESS on success, or an error code. **/ int gnutls_prf (gnutls_session_t session, @@ -1030,7 +1031,7 @@ gnutls_prf (gnutls_session_t session, * will be garbage; in particular, a %NULL return value should not be * expected. * - * Return value: pointer to client random. + * Returns: pointer to client random data. **/ const void * gnutls_session_get_client_random (gnutls_session_t session) @@ -1049,7 +1050,7 @@ gnutls_session_get_client_random (gnutls_session_t session) * will be garbage; in particular, a %NULL return value should not be * expected. * - * Return value: pointer to server random. + * Returns: pointer to server random data. **/ const void * gnutls_session_get_server_random (gnutls_session_t session) @@ -1071,7 +1072,7 @@ gnutls_session_get_server_random (gnutls_session_t session) * Consider using gnutls_prf() rather than extracting the master * secret and use it to derive further data. * - * Return value: pointer to master secret. + * Returns: pointer to master secret data. **/ const void * gnutls_session_get_master_secret (gnutls_session_t session) @@ -1083,9 +1084,8 @@ gnutls_session_get_master_secret (gnutls_session_t session) * gnutls_session_is_resumed - Used to check whether this session is a resumed one * @session: is a #gnutls_session_t structure. * - * This function will return non zero if this session is a resumed one, - * or a zero if this is a new session. - * + * Returns: non zero if this session is resumed, or a zero if this is + * a new session. **/ int gnutls_session_is_resumed (gnutls_session_t session) @@ -1136,9 +1136,8 @@ _gnutls_session_is_export (gnutls_session_t session) * gnutls_session_get_ptr - Used to get the user pointer from the session structure * @session: is a #gnutls_session_t structure. * - * This function will return the user given pointer from the session structure. - * This is the pointer set with gnutls_session_set_ptr(). - * + * Returns: the user given pointer from the session structure. This + * is the pointer set with gnutls_session_set_ptr(). **/ void * gnutls_session_get_ptr (gnutls_session_t session) @@ -1154,7 +1153,6 @@ gnutls_session_get_ptr (gnutls_session_t session) * This function will set (associate) the user given pointer to the * session structure. This is pointer can be accessed with * gnutls_session_get_ptr(). - * **/ void gnutls_session_set_ptr (gnutls_session_t session, void *ptr) @@ -1167,16 +1165,18 @@ gnutls_session_set_ptr (gnutls_session_t session, void *ptr) * gnutls_record_get_direction - This function will return the direction of the last interrupted function call * @session: is a #gnutls_session_t structure. * - * This function provides information about the internals of the record - * protocol and is only useful if a prior gnutls function call (e.g. - * gnutls_handshake()) was interrupted for some reason, that is, if a function - * returned GNUTLS_E_INTERRUPTED or GNUTLS_E_AGAIN. In such a case, you might - * want to call select() or poll() before calling the interrupted gnutls - * function again. To tell you whether a file descriptor should be selected - * for either reading or writing, gnutls_record_get_direction() returns 0 if - * the interrupted function was trying to read data, and 1 if it was trying to - * write data. + * This function provides information about the internals of the + * record protocol and is only useful if a prior gnutls function call + * (e.g. gnutls_handshake()) was interrupted for some reason, that + * is, if a function returned %GNUTLS_E_INTERRUPTED or + * %GNUTLS_E_AGAIN. In such a case, you might want to call select() + * or poll() before calling the interrupted gnutls function again. + * To tell you whether a file descriptor should be selected for + * either reading or writing, gnutls_record_get_direction() returns 0 + * if the interrupted function was trying to read data, and 1 if it + * was trying to write data. * + * Returns: 0 if trying to read data, 1 if trying to write data. **/ int gnutls_record_get_direction (gnutls_session_t session) @@ -1208,25 +1208,26 @@ _gnutls_rsa_pms_set_version (gnutls_session_t session, * @res: is a gnutls_anon_server_credentials_t structure * @func: is the function to be called * - * This function will set a callback to be called after the client hello - * has been received (callback valid in server side only). This allows the - * server to adjust settings based on received extensions. + * This function will set a callback to be called after the client + * hello has been received (callback valid in server side only). This + * allows the server to adjust settings based on received extensions. * - * Those settings could be ciphersuites, requesting certificate, or anything - * else except for version negotiation (this is done before the hello message - * is parsed). + * Those settings could be ciphersuites, requesting certificate, or + * anything else except for version negotiation (this is done before + * the hello message is parsed). * * This callback must return 0 on success or a gnutls error code to * terminate the handshake. * - * NOTE: You should not use this function to terminate the handshake based - * on client input unless you know what you are doing. Before the handshake - * is finished there is no way to know if there is a man-in-the-middle attack - * being performed. + * NOTE: You should not use this function to terminate the handshake + * based on client input unless you know what you are doing. Before + * the handshake is finished there is no way to know if there is a + * man-in-the-middle attack being performed. * **/ -void gnutls_handshake_set_post_client_hello_function( gnutls_session_t session, - gnutls_handshake_post_client_hello_func func) +void +gnutls_handshake_set_post_client_hello_function (gnutls_session_t session, + gnutls_handshake_post_client_hello_func func) { session->internals.user_hello_func = func; } @@ -1235,14 +1236,13 @@ void gnutls_handshake_set_post_client_hello_function( gnutls_session_t session, * gnutls_session_enable_compatibility_mode - Used to disable certain features in TLS in order to honour compatibility * @session: is a #gnutls_session_t structure. * - * This function can be used to disable certain (security) features in TLS - * in order to maintain maximum compatibility with buggy clients. It is - * equivalent to calling: + * This function can be used to disable certain (security) features + * in TLS in order to maintain maximum compatibility with buggy + * clients. It is equivalent to calling: * gnutls_record_disable_padding() * - * Normally only servers that require maximum compatibility with everything - * out there, need to call this function. - * + * Normally only servers that require maximum compatibility with + * everything out there, need to call this function. **/ void gnutls_session_enable_compatibility_mode (gnutls_session_t session) -- cgit v1.2.1