/soc/2013/ankitkv/gobjectification: 2e45aee0af19: Documented fun...
Ankit Vani
a at nevitus.org
Sat Jun 29 09:30:14 EDT 2013
Changeset: 2e45aee0af192fe862d160b68463b7fd8711f303
Author: Ankit Vani <a at nevitus.org>
Date: 2013-06-29 19:00 +0530
Branch: soc.2013.gobjectification
URL: https://hg.pidgin.im/soc/2013/ankitkv/gobjectification/rev/2e45aee0af19
Description:
Documented functions of PurpleCipher, PurpleHash and purple_account_get_type()
diffstat:
libpurple/account.h | 7 +-
libpurple/cipher.h | 140 ++++++++++++++++++++++++++++++++++++++++++++++++++++
libpurple/hash.h | 71 ++++++++++++++++++++++++++
3 files changed, 216 insertions(+), 2 deletions(-)
diffs (294 lines):
diff --git a/libpurple/account.h b/libpurple/account.h
--- a/libpurple/account.h
+++ b/libpurple/account.h
@@ -120,14 +120,17 @@ struct _PurpleAccountClass {
G_BEGIN_DECLS
-GType purple_account_get_type(void);
-
/**************************************************************************/
/** @name Account API */
/**************************************************************************/
/*@{*/
/**
+ * Returns the GType for the Account object.
+ */
+GType purple_account_get_type(void);
+
+/**
* Creates a new account.
*
* @param username The username.
diff --git a/libpurple/cipher.h b/libpurple/cipher.h
--- a/libpurple/cipher.h
+++ b/libpurple/cipher.h
@@ -132,32 +132,172 @@ struct _PurpleCipherClass {
G_BEGIN_DECLS
+/*****************************************************************************/
+/** @name PurpleCipher API */
+/*****************************************************************************/
+/*@{*/
+
+/**
+ * Returns the GType for the Cipher object.
+ */
GType purple_cipher_get_type(void);
+/**
+ * Gets a cipher's name
+ *
+ * @param cipher The cipher
+ *
+ * @return The cipher's name
+ */
const gchar *purple_cipher_get_name(PurpleCipher *cipher);
+/**
+ * Resets a cipher to it's default value
+ * @note If you have set an IV you will have to set it after resetting
+ *
+ * @param cipher The cipher
+ */
void purple_cipher_reset(PurpleCipher *cipher);
+
+/**
+ * Resets a cipher state to it's default value, but doesn't touch stateless
+ * configuration.
+ *
+ * That means, IV and digest will be wiped out, but keys, ops or salt
+ * will remain untouched.
+ *
+ * @param cipher The cipher
+ */
void purple_cipher_reset_state(PurpleCipher *cipher);
+
+/**
+ * Sets the initialization vector for a cipher
+ * @note This should only be called right after a cipher is created or reset
+ *
+ * @param cipher The cipher
+ * @param iv The initialization vector to set
+ * @param len The len of the IV
+ */
void purple_cipher_set_iv(PurpleCipher *cipher, guchar *iv, size_t len);
+/**
+ * Appends data to the cipher context
+ *
+ * @param cipher The cipher
+ * @param data The data to append
+ * @param len The length of the data
+ */
void purple_cipher_append(PurpleCipher *cipher, const guchar *data, size_t len);
+
+/**
+ * Digests a cipher context
+ *
+ * @param cipher The cipher
+ * @param digest The return buffer for the digest
+ * @param len The length of the buffer
+ */
gboolean purple_cipher_digest(PurpleCipher *cipher, guchar digest[], size_t len);
+
+/**
+ * Converts a guchar digest into a hex string
+ *
+ * @param cipher The cipher
+ * @param digest_s The return buffer for the string digest
+ * @param len The length of the buffer
+ */
gboolean purple_cipher_digest_to_str(PurpleCipher *cipher, gchar digest_s[], size_t len);
+
+/**
+ * Gets the digest size of a cipher
+ *
+ * @param cipher The cipher whose digest size to get
+ *
+ * @return The digest size of the cipher
+ */
size_t purple_cipher_get_digest_size(PurpleCipher *cipher);
+/**
+ * Encrypts data using the cipher
+ *
+ * @param cipher The cipher
+ * @param input The data to encrypt
+ * @param in_len The length of the data
+ * @param output The output buffer
+ * @param out_size The size of the output buffer
+ *
+ * @return A length of data that was outputed or -1, if failed
+ */
ssize_t purple_cipher_encrypt(PurpleCipher *cipher, const guchar input[], size_t in_len, guchar output[], size_t out_size);
+
+/**
+ * Decrypts data using the cipher
+ *
+ * @param cipher The cipher
+ * @param input The data to encrypt
+ * @param in_len The length of the returned value
+ * @param output The output buffer
+ * @param out_size The size of the output buffer
+ *
+ * @return A length of data that was outputed or -1, if failed
+ */
ssize_t purple_cipher_decrypt(PurpleCipher *cipher, const guchar input[], size_t in_len, guchar output[], size_t out_size);
+/**
+ * Sets the salt on a cipher
+ *
+ * @param cipher The cipher whose salt to set
+ * @param salt The salt
+ * @param len The length of the salt
+ */
void purple_cipher_set_salt(PurpleCipher *cipher, const guchar *salt, size_t len);
+/**
+ * Sets the key on a cipher
+ *
+ * @param cipher The cipher whose key to set
+ * @param key The key
+ * @param len The size of the key
+ */
void purple_cipher_set_key(PurpleCipher *cipher, const guchar *key, size_t len);
+
+/**
+ * Gets the size of the key if the cipher supports it
+ *
+ * @param cipher The cipher whose key size to get
+ *
+ * @return The size of the key
+ */
size_t purple_cipher_get_key_size(PurpleCipher *cipher);
+/**
+ * Sets the batch mode of a cipher
+ *
+ * @param cipher The cipher whose batch mode to set
+ * @param mode The batch mode under which the cipher should operate
+ *
+ */
void purple_cipher_set_batch_mode(PurpleCipher *cipher, PurpleCipherBatchMode mode);
+
+/**
+ * Gets the batch mode of a cipher
+ *
+ * @param cipher The cipher whose batch mode to get
+ *
+ * @return The batch mode under which the cipher is operating
+ */
PurpleCipherBatchMode purple_cipher_get_batch_mode(PurpleCipher *cipher);
+/**
+ * Gets the block size of a cipher
+ *
+ * @param cipher The cipher whose block size to get
+ *
+ * @return The block size of the cipher
+ */
size_t purple_cipher_get_block_size(PurpleCipher *cipher);
+/*@}*/
+
G_END_DECLS
#endif /* PURPLE_CIPHER_H */
diff --git a/libpurple/hash.h b/libpurple/hash.h
--- a/libpurple/hash.h
+++ b/libpurple/hash.h
@@ -96,20 +96,91 @@ struct _PurpleHashClass {
G_BEGIN_DECLS
+/*****************************************************************************/
+/** @name PurpleHash API */
+/*****************************************************************************/
+/*@{*/
+
+/**
+ * Returns the GType for the Hash object.
+ */
GType purple_hash_get_type(void);
+/**
+ * Gets a hash's name
+ *
+ * @param hash The hash
+ *
+ * @return The hash's name
+ */
const gchar *purple_hash_get_name(PurpleHash *hash);
+/**
+ * Resets a hash to it's default value
+ * @note If you have set an IV you will have to set it after resetting
+ *
+ * @param hash The hash
+ */
void purple_hash_reset(PurpleHash *hash);
+
+/**
+ * Resets a hash state to it's default value, but doesn't touch stateless
+ * configuration.
+ *
+ * That means, IV and digest will be wiped out, but keys, ops or salt
+ * will remain untouched.
+ *
+ * @param hash The hash
+ */
void purple_hash_reset_state(PurpleHash *hash);
+/**
+ * Appends data to the hash context
+ *
+ * @param hash The hash
+ * @param data The data to append
+ * @param len The length of the data
+ */
void purple_hash_append(PurpleHash *hash, const guchar *data, size_t len);
+
+/**
+ * Digests a hash context
+ *
+ * @param hash The hash
+ * @param digest The return buffer for the digest
+ * @param len The length of the buffer
+ */
gboolean purple_hash_digest(PurpleHash *hash, guchar digest[], size_t len);
+
+/**
+ * Converts a guchar digest into a hex string
+ *
+ * @param hash The hash
+ * @param digest_s The return buffer for the string digest
+ * @param len The length of the buffer
+ */
gboolean purple_hash_digest_to_str(PurpleHash *hash, gchar digest_s[], size_t len);
+
+/**
+ * Gets the digest size of a hash
+ *
+ * @param hash The hash whose digest size to get
+ *
+ * @return The digest size of the hash
+ */
size_t purple_hash_get_digest_size(PurpleHash *hash);
+/**
+ * Gets the block size of a hash
+ *
+ * @param hash The hash whose block size to get
+ *
+ * @return The block size of the hash
+ */
size_t purple_hash_get_block_size(PurpleHash *hash);
+/*@}*/
+
G_END_DECLS
#endif /* PURPLE_HASH_H */
More information about the Commits
mailing list