![]() |
![]() |
![]() |
GLib Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#include <glib.h> enum GChecksumType; gssize g_checksum_type_get_length (GChecksumType checksum_type); GChecksum; GChecksum * g_checksum_new (GChecksumType checksum_type); GChecksum * g_checksum_copy (const GChecksum *checksum); void g_checksum_free (GChecksum *checksum); void g_checksum_reset (GChecksum *checksum); void g_checksum_update (GChecksum *checksum, const guchar *data, gssize length); const gchar * g_checksum_get_string (GChecksum *checksum); void g_checksum_get_digest (GChecksum *checksum, guint8 *buffer, gsize *digest_len); gchar * g_compute_checksum_for_data (GChecksumType checksum_type, const guchar *data, gsize length); gchar * g_compute_checksum_for_string (GChecksumType checksum_type, const gchar *str, gssize length);
GLib provides a generic API for computing checksums (or "digests") for a sequence of arbitrary bytes, using various hashing algorithms like MD5, SHA-1 and SHA-256. Checksums are commonly used in various environments and specifications.
GLib supports incremental checksums using the GChecksum data structure, by
calling g_checksum_update()
as long as there's data available and then using
g_checksum_get_string()
or g_checksum_get_digest()
to compute the checksum
and return it either as a string in hexadecimal form, or as a raw sequence
of bytes. To compute the checksum for binary blobs and NUL-terminated strings
in one go, use the convenience functions g_compute_checksum_for_data()
and
g_compute_checksum_for_string()
, respectively.
Support for checksums has been added in GLib 2.16
typedef enum { G_CHECKSUM_MD5, G_CHECKSUM_SHA1, G_CHECKSUM_SHA256 } GChecksumType;
The hashing algorithm to be used by GChecksum when performing the digest of some data.
Note that the GChecksumType enumeration may be extended at a later date to include new hashing algorithm types.
Use the MD5 hashing algorithm | |
Use the SHA-1 hashing algorithm | |
Use the SHA-256 hashing algorithm |
Since 2.16
gssize g_checksum_type_get_length (GChecksumType checksum_type);
Gets the length in bytes of digests of type checksum_type
|
a GChecksumType |
Returns : |
the checksum length, or -1 if checksum_type is
not supported.
|
Since 2.16
typedef struct _GChecksum GChecksum;
An opaque structure representing a checksumming operation.
To create a new GChecksum, use g_checksum_new()
. To free
a GChecksum, use g_checksum_free()
.
Since 2.16
GChecksum * g_checksum_new (GChecksumType checksum_type);
Creates a new GChecksum, using the checksum algorithm checksum_type
.
If the checksum_type
is not known, NULL
is returned.
A GChecksum can be used to compute the checksum, or digest, of an
arbitrary binary blob, using different hashing algorithms.
A GChecksum works by feeding a binary blob through g_checksum_update()
until there is data to be checked; the digest can then be extracted
using g_checksum_get_string()
, which will return the checksum as a
hexadecimal string; or g_checksum_get_digest()
, which will return a
vector of raw bytes. Once either g_checksum_get_string()
or
g_checksum_get_digest()
have been called on a GChecksum, the checksum
will be closed and it won't be possible to call g_checksum_update()
on it anymore.
|
the desired type of checksum |
Returns : |
the newly created GChecksum, or NULL .
Use g_checksum_free() to free the memory allocated by it.
|
Since 2.16
GChecksum * g_checksum_copy (const GChecksum *checksum);
Copies a GChecksum. If checksum
has been closed, by calling
g_checksum_get_string()
or g_checksum_get_digest()
, the copied
checksum will be closed as well.
|
the GChecksum to copy |
Returns : |
the copy of the passed GChecksum. Use g_checksum_free()
when finished using it.
|
Since 2.16
void g_checksum_free (GChecksum *checksum);
Frees the memory allocated for checksum
.
|
a GChecksum |
Since 2.16
void g_checksum_reset (GChecksum *checksum);
Resets the state of the checksum
back to its initial state.
|
the GChecksum to reset |
Since 2.18
void g_checksum_update (GChecksum *checksum, const guchar *data, gssize length);
Feeds data
into an existing GChecksum. The checksum must still be
open, that is g_checksum_get_string()
or g_checksum_get_digest()
must
not have been called on checksum
.
|
a GChecksum |
|
buffer used to compute the checksum |
|
size of the buffer, or -1 if it is a null-terminated string. |
Since 2.16
const gchar * g_checksum_get_string (GChecksum *checksum);
Gets the digest as an hexadecimal string.
Once this function has been called the GChecksum can no longer be
updated with g_checksum_update()
.
The hexadecimal characters will be lower case.
|
a GChecksum |
Returns : |
the hexadecimal representation of the checksum. The returned string is owned by the checksum and should not be modified or freed. |
Since 2.16
void g_checksum_get_digest (GChecksum *checksum, guint8 *buffer, gsize *digest_len);
Gets the digest from checksum
as a raw binary vector and places it
into buffer
. The size of the digest depends on the type of checksum.
Once this function has been called, the GChecksum is closed and can
no longer be updated with g_checksum_update()
.
|
a GChecksum |
|
output buffer |
|
an inout parameter. The caller initializes it to the size of buffer .
After the call it contains the length of the digest.
|
Since 2.16
gchar * g_compute_checksum_for_data (GChecksumType checksum_type, const guchar *data, gsize length);
Computes the checksum for a binary data
of length
. This is a
convenience wrapper for g_checksum_new()
, g_checksum_get_string()
and g_checksum_free()
.
The hexadecimal string returned will be in lower case.
|
a GChecksumType |
|
binary blob to compute the digest of |
|
length of data
|
Returns : |
the digest of the binary data as a string in hexadecimal.
The returned string should be freed with g_free() when done using it.
|
Since 2.16
gchar * g_compute_checksum_for_string (GChecksumType checksum_type, const gchar *str, gssize length);
Computes the checksum of a string.
The hexadecimal string returned will be in lower case.
|
a GChecksumType |
|
the string to compute the checksum of |
|
the length of the string, or -1 if the string is null-terminated. |
Returns : |
the checksum as a hexadecimal string. The returned string
should be freed with g_free() when done using it.
|
Since 2.16