Browse Source

Complete documentation of the secretcfg module

develop
Damien Goutte-Gattat 5 years ago
parent
commit
6c4f64d66e
  1. 59
      src/secretcfg.c

59
src/secretcfg.c

@ -34,9 +34,9 @@
* newline character is not stored, and if the line to read is too long
* to fit into the provided buffer, the whole line is discarded.
*
* @param f The stream to read from.
* @param f The stream to read from.
* @param buffer A character buffer to store the line into.
* @param len Size of the \a buffer array.
* @param len Size of the \a buffer array.
*
* @return The number of characters read, or one of the GFSEC_ERR_*
* error codes.
@ -63,16 +63,17 @@ get_line(FILE *f, char *buffer, size_t len)
return n;
}
/**
* Reads the provided string up to the first '/' character.
* The pointer is advanced to that character.
* Extracts the authority portion from a URI string.
* Reads the provided string up to first '/' character.
*
* The authority pointer receives a newly allocated copy of
* the string before the '/' character.
* @param uri The address of the URI string. The pointer is
* advanced to the '/' character separating the
* authority from the path.
* @param autorithy The address of a newly allocated buffer to store
* the authority.
*
* @return 0 if successful, or one of the GFSEC_ERR_*
* error codes.
* @return 0 if successfull, or one of the GFSEC_ERR_* error codes.
*/
static int
parse_authority(const char **uri, char **authority)
@ -91,14 +92,15 @@ parse_authority(const char **uri, char **authority)
}
/**
* Extracts the path portion from a URI string.
* Reads the provided string up to its end or up to the first
* '?' character (marking the end of the 'path' part of an URI).
* The pointer is advanced to that character, or to the
* terminating NULL byte.
*
* The path pointer receives a newly allocated copy of the part
* of the string before the '?' character (or the whole string
* if no '?' is found).
* @param uri The address of the URI string. The pointer is advanced
* to the first '?' character, or to the terminating NULL
* byte.
* @param path The address of a newly allocated buffer to store the
* extracted path.
*
* @return 0 if the path was successfully parsed, or one of
* the GFSEC_ERR_* error codes.
@ -121,10 +123,10 @@ parse_path(const char **uri, char **path)
/**
* Parses a hexadecimal-encoded SHA-256 hash value.
*
* @param hex The encoded hash to parse.
* @param len The length of the \a hex buffer.
* @param[out] sha256 A pointer to a newly-allocated buffer
* to store the hash value.
* @param hex The encoded hash to parse.
* @param len The length of the hex buffer.
* @param sha256 The address of a newly allocated buffer to store
* the hash value.
*
* @return 0 if the hash value was successfully parsed,
* or one of the GFSEC_ERR_* error codes.
@ -169,8 +171,12 @@ parse_sha256(const char *hex, size_t len, unsigned char **sha256)
/**
* Parses a name=value parameter in the provided string.
* Advances the pointer to the next character after the
* value.
*
* @param uri The address of the string containing the URI to
* parse. The pointer is advanced to the character
* located after the value.
* @param share The share object to which the parameter will be
* assigned.
*
* @return 0 if a correctly formed name=value pair was
* found, or one of the GFSEC_ERR_* error codes.
@ -213,6 +219,8 @@ parse_parameter(const char **uri, gfsec_share_t *share)
* Extract the share number from the last 3 characters of the
* specified path.
*
* @param path The path to extract the share number from.
*
* @return The share number, or 0 if the path does not end
* with a correctly formatted share number.
*/
@ -242,6 +250,10 @@ get_share_number_from_path(const char *path)
/**
* Parses the specified URI into a share object.
*
* @param uri The URI to parse.
* @param secret The gfsec_secret_t object to which a share
* will be added if the URI is correctly parsed.
*
* @return 0 if the URI was successfully parsed, or one of the
* GFSEC_ERR_* error codes.
*/
@ -292,6 +304,13 @@ parse_uri(const char *uri, gfsec_secret_t *secret)
/**
* Parses the specified configuration file.
*
* @param cfg The address of a pointer to a gfsec_secret_t
* structure which will be automatically allocated
* in this function.
* @param filename The location of the configuration file.
* @param line The address of an integer which will be set to the
* number of the last line read (may be NULL).
*
* @return
* - 0 if successful;
* - GFSEC_ERR_INVALID_CALL if an invalid pointer was passed;

Loading…
Cancel
Save