diff options
author | Simon Josefsson <simon@josefsson.org> | 2008-03-06 16:13:57 +0100 |
---|---|---|
committer | Simon Josefsson <simon@josefsson.org> | 2008-03-06 16:13:57 +0100 |
commit | d35108335cf1536e660108e025edf8a10c67993d (patch) | |
tree | f15b17f4f0aef677581663904f0c8ce09bc2e520 | |
parent | 5d90fd1606e0b68dcb0c1b29a960ca6094f824ea (diff) | |
download | gnutls-d35108335cf1536e660108e025edf8a10c67993d.tar.gz |
Doc fixes.
-rw-r--r-- | lib/gnutls_auth.c | 20 | ||||
-rw-r--r-- | lib/gnutls_openpgp.c | 79 | ||||
-rw-r--r-- | lib/gnutls_srp.c | 42 | ||||
-rw-r--r-- | libextra/gnutls_ia.c | 16 |
4 files changed, 91 insertions, 66 deletions
diff --git a/lib/gnutls_auth.c b/lib/gnutls_auth.c index fada7f3d4a..dc20149566 100644 --- a/lib/gnutls_auth.c +++ b/lib/gnutls_auth.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2001, 2002, 2003, 2004, 2005 Free Software Foundation + * Copyright (C) 2001, 2002, 2003, 2004, 2005, 2008 Free Software Foundation * * Author: Nikos Mavrogiannopoulos * @@ -156,9 +156,13 @@ gnutls_credentials_set (gnutls_session_t session, * Returns type of credentials for the current authentication schema. * The returned information is to be used to distinguish the function used * to access authentication data. - * - * Eg. for CERTIFICATE ciphersuites (key exchange algorithms: KX_RSA, KX_DHE_RSA), - * the same function are to be used to access the authentication data. + * + * Eg. for CERTIFICATE ciphersuites (key exchange algorithms: KX_RSA, + * KX_DHE_RSA), the same function are to be used to access the + * authentication data. + * + * Returns: The type of credentials for the current authentication + * schema, an #gnutls_credentials_type_t type. **/ gnutls_credentials_type_t gnutls_auth_get_type (gnutls_session_t session) @@ -181,7 +185,9 @@ gnutls_auth_get_type (gnutls_session_t session) * Returns the type of credentials that were used for server authentication. * The returned information is to be used to distinguish the function used * to access authentication data. - * + * + * Returns: The type of credentials for the server authentication + * schema, an #gnutls_credentials_type_t type. **/ gnutls_credentials_type_t gnutls_auth_server_get_type (gnutls_session_t session) @@ -199,7 +205,9 @@ gnutls_auth_server_get_type (gnutls_session_t session) * Returns the type of credentials that were used for client authentication. * The returned information is to be used to distinguish the function used * to access authentication data. - * + * + * Returns: The type of credentials for the client authentication + * schema, an #gnutls_credentials_type_t type. **/ gnutls_credentials_type_t gnutls_auth_client_get_type (gnutls_session_t session) diff --git a/lib/gnutls_openpgp.c b/lib/gnutls_openpgp.c index 97f90cef5d..51a99a1d50 100644 --- a/lib/gnutls_openpgp.c +++ b/lib/gnutls_openpgp.c @@ -323,8 +323,8 @@ stream_to_datum (cdk_stream_t inp, gnutls_datum_t * raw) * This funtion is used to load OpenPGP keys into the GnuTLS credential * structure. The files should contain non encrypted keys. * - * Returns a negative error value on error. - * + * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a + * negative error value. **/ int gnutls_certificate_set_openpgp_key_mem (gnutls_certificate_credentials_t @@ -332,7 +332,8 @@ gnutls_certificate_set_openpgp_key_mem (gnutls_certificate_credentials_t const gnutls_datum_t * ikey, gnutls_openpgp_crt_fmt_t format) { - return gnutls_certificate_set_openpgp_key_mem2( res, icert, ikey, NULL, format); + return gnutls_certificate_set_openpgp_key_mem2 (res, icert, ikey, + NULL, format); } @@ -343,11 +344,12 @@ gnutls_certificate_set_openpgp_key_mem (gnutls_certificate_credentials_t * @keyfile: the file that contains the secret key. * @format: the format of the keys * - * This funtion is used to load OpenPGP keys into the GnuTLS credentials structure. - * The files should only contain one key which is not encrypted. - * - * Returns a negative error value on error. + * This funtion is used to load OpenPGP keys into the GnuTLS + * credentials structure. The files should only contain one key which + * is not encrypted. * + * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a + * negative error value. **/ int gnutls_certificate_set_openpgp_key_file (gnutls_certificate_credentials_t @@ -355,7 +357,8 @@ gnutls_certificate_set_openpgp_key_file (gnutls_certificate_credentials_t const char *keyfile, gnutls_openpgp_crt_fmt_t format) { - return gnutls_certificate_set_openpgp_key_file2( res, certfile, keyfile, NULL, format); + return gnutls_certificate_set_openpgp_key_file2 (res, certfile, + keyfile, NULL, format); } static int get_keyid( gnutls_openpgp_keyid_t keyid, const char* str) @@ -385,14 +388,16 @@ static int get_keyid( gnutls_openpgp_keyid_t keyid, const char* str) * @subkey_id: a hex encoded subkey id * @format: the format of the keys * - * This funtion is used to load OpenPGP keys into the GnuTLS credentials structure. - * The files should only contain one key which is not encrypted. - * - * The special keyword "auto" is also accepted as &subkey_id. In that case - * the gnutls_openpgp_crt_get_auth_subkey() will be used to retrieve the subkey. + * This funtion is used to load OpenPGP keys into the GnuTLS + * credentials structure. The files should only contain one key which + * is not encrypted. * - * Returns a negative error value on error. + * The special keyword "auto" is also accepted as &subkey_id. In that + * case the gnutls_openpgp_crt_get_auth_subkey() will be used to + * retrieve the subkey. * + * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a + * negative error value. **/ int gnutls_certificate_set_openpgp_key_mem2 (gnutls_certificate_credentials_t @@ -404,7 +409,7 @@ gnutls_certificate_set_openpgp_key_mem2 (gnutls_certificate_credentials_t gnutls_openpgp_privkey_t key; gnutls_openpgp_crt_t cert; int ret; - + ret = gnutls_openpgp_privkey_init( &key); if (ret < 0) { gnutls_assert(); @@ -481,8 +486,8 @@ gnutls_certificate_set_openpgp_key_mem2 (gnutls_certificate_credentials_t * The special keyword "auto" is also accepted as &subkey_id. In that case * the gnutls_openpgp_crt_get_auth_subkey() will be used to retrieve the subkey. * - * Returns a negative error value on error. - * + * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a + * negative error value. **/ int gnutls_certificate_set_openpgp_key_file2 (gnutls_certificate_credentials_t @@ -585,8 +590,8 @@ gnutls_openpgp_count_key_names (const gnutls_datum_t * cert) * is needed for an operations. The keyring will also be used at the * verification functions. * - * Returns a negative error value on error. - * + * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a + * negative error value. **/ int gnutls_certificate_set_openpgp_keyring_file (gnutls_certificate_credentials_t c, @@ -629,8 +634,8 @@ gnutls_certificate_set_openpgp_keyring_file (gnutls_certificate_credentials_t c, * is needed for an operations. The keyring will also be used at the * verification functions. * - * Returns a negative error value on error. - * + * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a + * negative error value. **/ int gnutls_certificate_set_openpgp_keyring_mem (gnutls_certificate_credentials_t @@ -918,23 +923,23 @@ _gnutls_openpgp_crt_to_gcert (gnutls_cert * gcert, gnutls_openpgp_crt_t cert) * @hash: holds the data to be signed * @signature: will contain newly allocated signature * - * This function will sign the given hash using the private key. - * You should use gnutls_openpgp_privkey_set_subkey() before calling this function - * to set the subkey to use. + * This function will sign the given hash using the private key. You + * should use gnutls_openpgp_privkey_set_subkey() before calling this + * function to set the subkey to use. * - * Return value: In case of failure a negative value will be returned, - * and 0 on success. + * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a + * negative error value. **/ int gnutls_openpgp_privkey_sign_hash (gnutls_openpgp_privkey_t key, const gnutls_datum_t * hash, gnutls_datum_t * signature) { -int result, i; -mpi_t params[MAX_PUBLIC_PARAMS_SIZE]; -int params_size = MAX_PUBLIC_PARAMS_SIZE; -int pk_algorithm; -gnutls_openpgp_keyid_t keyid; + int result, i; + mpi_t params[MAX_PUBLIC_PARAMS_SIZE]; + int params_size = MAX_PUBLIC_PARAMS_SIZE; + int pk_algorithm; + gnutls_openpgp_keyid_t keyid; if (key == NULL) { @@ -946,15 +951,17 @@ gnutls_openpgp_keyid_t keyid; if (result == 0) { uint32_t kid[2]; - + KEYID_IMPORT( kid, keyid); - result = _gnutls_openpgp_privkey_get_mpis( key, kid, params, ¶ms_size); + result = _gnutls_openpgp_privkey_get_mpis (key, kid, + params, ¶ms_size); } else { - result = _gnutls_openpgp_privkey_get_mpis( key, NULL, params, ¶ms_size); + result = _gnutls_openpgp_privkey_get_mpis (key, NULL, + params, ¶ms_size); } - + if (result < 0) { gnutls_assert (); @@ -968,7 +975,7 @@ gnutls_openpgp_keyid_t keyid; for (i=0;i<params_size;i++) _gnutls_mpi_release( ¶ms[i]); - + if (result < 0) { gnutls_assert (); diff --git a/lib/gnutls_srp.c b/lib/gnutls_srp.c index 4c9cdef772..d2e6498e5b 100644 --- a/lib/gnutls_srp.c +++ b/lib/gnutls_srp.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2001, 2002, 2003, 2004, 2005 Free Software Foundation + * Copyright (C) 2001, 2002, 2003, 2004, 2005, 2008 Free Software Foundation * * Author: Nikos Mavrogiannopoulos * @@ -422,7 +422,8 @@ gnutls_srp_free_client_credentials (gnutls_srp_client_credentials_t sc) * This structure is complex enough to manipulate directly thus * this helper function is provided in order to allocate it. * - * Returns 0 on success. + * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, or an + * error code. **/ int gnutls_srp_allocate_client_credentials (gnutls_srp_client_credentials_t * sc) @@ -441,11 +442,14 @@ gnutls_srp_allocate_client_credentials (gnutls_srp_client_credentials_t * sc) * @username: is the user's userid * @password: is the user's password * - * This function sets the username and password, in a gnutls_srp_client_credentials_t structure. - * Those will be used in SRP authentication. @username and @password should be ASCII - * strings or UTF-8 strings prepared using the "SASLprep" profile of "stringprep". + * This function sets the username and password, in a + * #gnutls_srp_client_credentials_t structure. Those will be used in + * SRP authentication. @username and @password should be ASCII + * strings or UTF-8 strings prepared using the "SASLprep" profile of + * "stringprep". * - * Returns 0 on success. + * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, or an + * error code. **/ int gnutls_srp_set_client_credentials (gnutls_srp_client_credentials_t res, @@ -493,10 +497,11 @@ gnutls_srp_free_server_credentials (gnutls_srp_server_credentials_t sc) * gnutls_srp_allocate_server_credentials - Used to allocate an gnutls_srp_server_credentials_t structure * @sc: is a pointer to an #gnutls_srp_server_credentials_t structure. * - * This structure is complex enough to manipulate directly thus - * this helper function is provided in order to allocate it. - * - * Returns 0 on success. + * This structure is complex enough to manipulate directly thus this + * helper function is provided in order to allocate it. + * + * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, or an + * error code. **/ int gnutls_srp_allocate_server_credentials (gnutls_srp_server_credentials_t * sc) @@ -515,11 +520,13 @@ gnutls_srp_allocate_server_credentials (gnutls_srp_server_credentials_t * sc) * @password_file: is the SRP password file (tpasswd) * @password_conf_file: is the SRP password conf file (tpasswd.conf) * - * This function sets the password files, in a gnutls_srp_server_credentials_t structure. - * Those password files hold usernames and verifiers and will be used for SRP authentication. - * - * Returns 0 on success. + * This function sets the password files, in a + * #gnutls_srp_server_credentials_t structure. Those password files + * hold usernames and verifiers and will be used for SRP + * authentication. * + * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, or an + * error code. **/ int gnutls_srp_set_server_credentials_file (gnutls_srp_server_credentials_t @@ -643,10 +650,11 @@ gnutls_srp_set_client_credentials_function (gnutls_srp_client_credentials_t * gnutls_srp_server_get_username - return the username of the peer * @session: is a gnutls session * - * This function will return the username of the peer. This should only be - * called in case of SRP authentication and in case of a server. - * Returns NULL in case of an error. + * This function will return the username of the peer. This should + * only be called in case of SRP authentication and in case of a + * server. Returns NULL in case of an error. * + * Returns: SRP username of the peer, or NULL in case of error. **/ const char * gnutls_srp_server_get_username (gnutls_session_t session) diff --git a/libextra/gnutls_ia.c b/libextra/gnutls_ia.c index df45511bd0..ee23648d72 100644 --- a/libextra/gnutls_ia.c +++ b/libextra/gnutls_ia.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2005, 2006 Free Software Foundation + * Copyright (C) 2005, 2006, 2008 Free Software Foundation * * Author: Simon Josefsson * @@ -390,7 +390,7 @@ gnutls_ia_verify_endphase (gnutls_session_t session, const char *checksum) * this function again, with the same parameters; alternatively you * could provide a %NULL pointer for data, and 0 for size. * - * Returns the number of bytes sent, or a negative error code. + * Returns: The number of bytes sent, or a negative error code. **/ ssize_t gnutls_ia_send (gnutls_session_t session, const char *data, size_t sizeofdata) @@ -426,7 +426,7 @@ gnutls_ia_send (gnutls_session_t session, const char *data, size_t sizeofdata) * this function again, with the same parameters; alternatively you * could provide a NULL pointer for data, and 0 for size. * - * Returns the number of bytes received. A negative error code is + * Returns: The number of bytes received. A negative error code is * returned in case of an error. The * %GNUTLS_E_WARNING_IA_IPHF_RECEIVED and * %GNUTLS_E_WARNING_IA_FPHF_RECEIVED errors are returned when an @@ -658,7 +658,8 @@ gnutls_ia_handshake (gnutls_session_t session) * support TLS/IA). Use gnutls_ia_require_inner_phase() to toggle the * TLS/IA mode. * - * Returns 0 on success. + * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise + * an error code is returned. **/ int gnutls_ia_allocate_client_credentials (gnutls_ia_client_credentials_t * sc) @@ -733,7 +734,6 @@ gnutls_ia_set_client_avp_function (gnutls_ia_client_credentials_t cred, * * Sets the pointer that will be provided to the TLS/IA callback * function as the first argument. - * **/ void gnutls_ia_set_client_avp_ptr (gnutls_ia_client_credentials_t cred, void *ptr) @@ -748,6 +748,7 @@ gnutls_ia_set_client_avp_ptr (gnutls_ia_client_credentials_t cred, void *ptr) * Returns the pointer that will be provided to the TLS/IA callback * function as the first argument. * + * Returns: The client callback data pointer. **/ void * gnutls_ia_get_client_avp_ptr (gnutls_ia_client_credentials_t cred) @@ -767,7 +768,8 @@ gnutls_ia_get_client_avp_ptr (gnutls_ia_client_credentials_t cred) * support TLS/IA). Use gnutls_ia_require_inner_phase() to toggle the * TLS/IA mode. * - * Returns 0 on success. + * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise + * an error code is returned. **/ int gnutls_ia_allocate_server_credentials (gnutls_ia_server_credentials_t * sc) @@ -849,7 +851,6 @@ gnutls_ia_set_server_avp_function (gnutls_ia_server_credentials_t cred, * * Sets the pointer that will be provided to the TLS/IA callback * function as the first argument. - * **/ void gnutls_ia_set_server_avp_ptr (gnutls_ia_server_credentials_t cred, void *ptr) @@ -864,6 +865,7 @@ gnutls_ia_set_server_avp_ptr (gnutls_ia_server_credentials_t cred, void *ptr) * Returns the pointer that will be provided to the TLS/IA callback * function as the first argument. * + * Returns: The server callback data pointer. **/ void * gnutls_ia_get_server_avp_ptr (gnutls_ia_server_credentials_t cred) |