diff options
author | Alexander Smirnov <alex@ydb.tech> | 2024-10-19 17:59:18 +0000 |
---|---|---|
committer | Alexander Smirnov <alex@ydb.tech> | 2024-10-19 17:59:18 +0000 |
commit | ceddbfe68f6ec7949a4062716c8f9840a59c6888 (patch) | |
tree | abfecadbb9c1e5aea40701dd20d902cb7bccd962 /contrib/libs/c-ares/src/lib/include/ares_buf.h | |
parent | 07f2e60d02d95eab14a86a4b9469db1af7795001 (diff) | |
parent | d920c750e476fa2dc80c45f990d9456b1afeadd1 (diff) | |
download | ydb-ceddbfe68f6ec7949a4062716c8f9840a59c6888.tar.gz |
Merge branch 'rightlib' into mergelibs-241019-1758
Diffstat (limited to 'contrib/libs/c-ares/src/lib/include/ares_buf.h')
-rw-r--r-- | contrib/libs/c-ares/src/lib/include/ares_buf.h | 712 |
1 files changed, 712 insertions, 0 deletions
diff --git a/contrib/libs/c-ares/src/lib/include/ares_buf.h b/contrib/libs/c-ares/src/lib/include/ares_buf.h new file mode 100644 index 0000000000..7836a313e0 --- /dev/null +++ b/contrib/libs/c-ares/src/lib/include/ares_buf.h @@ -0,0 +1,712 @@ +/* MIT License + * + * Copyright (c) 2023 Brad House + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice (including the next + * paragraph) shall be included in all copies or substantial portions of the + * Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + * + * SPDX-License-Identifier: MIT + */ +#ifndef __ARES__BUF_H +#define __ARES__BUF_H + +#include "ares.h" +#include "ares_array.h" + +/*! \addtogroup ares_buf Safe Data Builder and buffer + * + * This is a buffer building and parsing framework with a focus on security over + * performance. All data to be read from the buffer will perform explicit length + * validation and return a success/fail result. There are also various helpers + * for writing data to the buffer which dynamically grows. + * + * All operations that fetch or consume data from the buffer will move forward + * the internal pointer, thus marking the data as processed which may no longer + * be accessible after certain operations (such as append). + * + * The helpers for this object are meant to be added as needed. If you can't + * find it, write it! + * + * @{ + */ +struct ares_buf; + +/*! Opaque data type for generic hash table implementation */ +typedef struct ares_buf ares_buf_t; + +/*! Create a new buffer object that dynamically allocates buffers for data. + * + * \return initialized buffer object or NULL if out of memory. + */ +CARES_EXTERN ares_buf_t *ares_buf_create(void); + +/*! Create a new buffer object that uses a user-provided data pointer. The + * data provided will not be manipulated, and cannot be appended to. This + * is strictly used for parsing. + * + * \param[in] data Data to provide to buffer, must not be NULL. + * \param[in] data_len Size of buffer provided, must be > 0 + * + * \return initialized buffer object or NULL if out of memory or misuse. + */ +CARES_EXTERN ares_buf_t *ares_buf_create_const(const unsigned char *data, + size_t data_len); + + +/*! Destroy an initialized buffer object. + * + * \param[in] buf Initialized buf object + */ +CARES_EXTERN void ares_buf_destroy(ares_buf_t *buf); + + +/*! Append multiple bytes to a dynamic buffer object + * + * \param[in] buf Initialized buffer object + * \param[in] data Data to copy to buffer object + * \param[in] data_len Length of data to copy to buffer object. + * \return ARES_SUCCESS or one of the c-ares error codes + */ +CARES_EXTERN ares_status_t ares_buf_append(ares_buf_t *buf, + const unsigned char *data, + size_t data_len); + +/*! Append a single byte to the dynamic buffer object + * + * \param[in] buf Initialized buffer object + * \param[in] b Single byte to append to buffer object. + * \return ARES_SUCCESS or one of the c-ares error codes + */ +CARES_EXTERN ares_status_t ares_buf_append_byte(ares_buf_t *buf, + unsigned char b); + +/*! Append a null-terminated string to the dynamic buffer object + * + * \param[in] buf Initialized buffer object + * \param[in] str String to append to buffer object. + * \return ARES_SUCCESS or one of the c-ares error codes + */ +CARES_EXTERN ares_status_t ares_buf_append_str(ares_buf_t *buf, + const char *str); + +/*! Append a 16bit Big Endian number to the buffer. + * + * \param[in] buf Initialized buffer object + * \param[out] u16 16bit integer + * \return ARES_SUCCESS or one of the c-ares error codes + */ +CARES_EXTERN ares_status_t ares_buf_append_be16(ares_buf_t *buf, + unsigned short u16); + +/*! Append a 32bit Big Endian number to the buffer. + * + * \param[in] buf Initialized buffer object + * \param[out] u32 32bit integer + * \return ARES_SUCCESS or one of the c-ares error codes + */ +CARES_EXTERN ares_status_t ares_buf_append_be32(ares_buf_t *buf, + unsigned int u32); + +/*! Append a number in ASCII decimal form. + * + * \param[in] buf Initialized buffer object + * \param[in] num Number to print + * \param[in] len Length to output, use 0 for no padding + * \return ARES_SUCCESS on success + */ +CARES_EXTERN ares_status_t ares_buf_append_num_dec(ares_buf_t *buf, size_t num, + size_t len); + +/*! Append a number in ASCII hexadecimal form. + * + * \param[in] buf Initialized buffer object + * \param[in] num Number to print + * \param[in] len Length to output, use 0 for no padding + * \return ARES_SUCCESS on success + */ +CARES_EXTERN ares_status_t ares_buf_append_num_hex(ares_buf_t *buf, size_t num, + size_t len); + +/*! Sets the current buffer length. This *may* be used if there is a need to + * override a prior position in the buffer, such as if there is a length + * prefix that isn't easily predictable, and you must go back and overwrite + * that position. + * + * Only valid on non-const buffers. Length provided must not exceed current + * allocated buffer size, but otherwise there are very few protections on + * this function. Use cautiously. + * + * \param[in] buf Initialized buffer object + * \param[in] len Length to set + * \return ARES_SUCCESS or one of the c-ares error codes + */ +CARES_EXTERN ares_status_t ares_buf_set_length(ares_buf_t *buf, size_t len); + + +/*! Start a dynamic append operation that returns a buffer suitable for + * writing. A desired minimum length is passed in, and the actual allocated + * buffer size is returned which may be greater than the requested size. + * No operation other than ares_buf_append_finish() is allowed on the + * buffer after this request. + * + * \param[in] buf Initialized buffer object + * \param[in,out] len Desired non-zero length passed in, actual buffer size + * returned. + * \return Pointer to writable buffer or NULL on failure (usage, out of mem) + */ +CARES_EXTERN unsigned char *ares_buf_append_start(ares_buf_t *buf, size_t *len); + +/*! Finish a dynamic append operation. Called after + * ares_buf_append_start() once desired data is written. + * + * \param[in] buf Initialized buffer object. + * \param[in] len Length of data written. May be zero to terminate + * operation. Must not be greater than returned from + * ares_buf_append_start(). + */ +CARES_EXTERN void ares_buf_append_finish(ares_buf_t *buf, size_t len); + +/*! Write the data provided to the buffer in a hexdump format. + * + * \param[in] buf Initialized buffer object. + * \param[in] data Data to hex dump + * \param[in] len Length of data to hexdump + * \return ARES_SUCCESS on success. + */ +CARES_EXTERN ares_status_t ares_buf_hexdump(ares_buf_t *buf, + const unsigned char *data, + size_t len); + +/*! Clean up ares_buf_t and return allocated pointer to unprocessed data. It + * is the responsibility of the caller to ares_free() the returned buffer. + * The passed in buf parameter is invalidated by this call. + * + * \param[in] buf Initialized buffer object. Can not be a "const" buffer. + * \param[out] len Length of data returned + * \return pointer to unprocessed data (may be zero length) or NULL on error. + */ +CARES_EXTERN unsigned char *ares_buf_finish_bin(ares_buf_t *buf, size_t *len); + +/*! Clean up ares_buf_t and return allocated pointer to unprocessed data and + * return it as a string (null terminated). It is the responsibility of the + * caller to ares_free() the returned buffer. The passed in buf parameter is + * invalidated by this call. + * + * This function in no way validates the data in this buffer is actually + * a string, that characters are printable, or that there aren't multiple + * NULL terminators. It is assumed that the caller will either validate that + * themselves or has built this buffer with only a valid character set. + * + * \param[in] buf Initialized buffer object. Can not be a "const" buffer. + * \param[out] len Optional. Length of data returned, or NULL if not needed. + * \return pointer to unprocessed data or NULL on error. + */ +CARES_EXTERN char *ares_buf_finish_str(ares_buf_t *buf, size_t *len); + +/*! Tag a position to save in the buffer in case parsing needs to rollback, + * such as if insufficient data is available, but more data may be added in + * the future. Only a single tag can be set per buffer object. Setting a + * tag will override any pre-existing tag. + * + * \param[in] buf Initialized buffer object + */ +CARES_EXTERN void ares_buf_tag(ares_buf_t *buf); + +/*! Rollback to a tagged position. Will automatically clear the tag. + * + * \param[in] buf Initialized buffer object + * \return ARES_SUCCESS or one of the c-ares error codes + */ +CARES_EXTERN ares_status_t ares_buf_tag_rollback(ares_buf_t *buf); + +/*! Clear the tagged position without rolling back. You should do this any + * time a tag is no longer needed as future append operations can reclaim + * buffer space. + * + * \param[in] buf Initialized buffer object + * \return ARES_SUCCESS or one of the c-ares error codes + */ +CARES_EXTERN ares_status_t ares_buf_tag_clear(ares_buf_t *buf); + +/*! Fetch the buffer and length of data starting from the tagged position up + * to the _current_ position. It will not unset the tagged position. The + * data may be invalidated by any future ares_buf_*() calls. + * + * \param[in] buf Initialized buffer object + * \param[out] len Length between tag and current offset in buffer + * \return NULL on failure (such as no tag), otherwise pointer to start of + * buffer + */ +CARES_EXTERN const unsigned char *ares_buf_tag_fetch(const ares_buf_t *buf, + size_t *len); + +/*! Get the length of the current tag offset to the current position. + * + * \param[in] buf Initialized buffer object + * \return length + */ +CARES_EXTERN size_t ares_buf_tag_length(const ares_buf_t *buf); + +/*! Fetch the bytes starting from the tagged position up to the _current_ + * position using the provided buffer. It will not unset the tagged position. + * + * \param[in] buf Initialized buffer object + * \param[in,out] bytes Buffer to hold data + * \param[in,out] len On input, buffer size, on output, bytes place in + * buffer. + * \return ARES_SUCCESS if fetched, ARES_EFORMERR if insufficient buffer size + */ +CARES_EXTERN ares_status_t ares_buf_tag_fetch_bytes(const ares_buf_t *buf, + unsigned char *bytes, + size_t *len); + +/*! Fetch the bytes starting from the tagged position up to the _current_ + * position as a NULL-terminated string using the provided buffer. The data + * is validated to be ASCII-printable data. It will not unset the tagged + * position. + * + * \param[in] buf Initialized buffer object + * \param[in,out] str Buffer to hold data + * \param[in] len buffer size + * \return ARES_SUCCESS if fetched, ARES_EFORMERR if insufficient buffer size, + * ARES_EBADSTR if not printable ASCII + */ +CARES_EXTERN ares_status_t ares_buf_tag_fetch_string(const ares_buf_t *buf, + char *str, size_t len); + +/*! Fetch the bytes starting from the tagged position up to the _current_ + * position as a NULL-terminated string and placed into a newly allocated + * buffer. The data is validated to be ASCII-printable data. It will not + * unset the tagged position. + * + * \param[in] buf Initialized buffer object + * \param[out] str New buffer to hold output, free with ares_free() + * + * \return ARES_SUCCESS if fetched, ARES_EFORMERR if insufficient buffer size, + * ARES_EBADSTR if not printable ASCII + */ +CARES_EXTERN ares_status_t ares_buf_tag_fetch_strdup(const ares_buf_t *buf, + char **str); + +/*! Fetch the bytes starting from the tagged position up to the _current_ + * position as const buffer. Care must be taken to not append or destroy the + * passed in buffer until the newly fetched buffer is no longer needed since + * it points to memory inside the passed in buffer which could be invalidated. + * + * \param[in] buf Initialized buffer object + * \param[out] newbuf New const buffer object, must be destroyed when done. + + * \return ARES_SUCCESS if fetched + */ +CARES_EXTERN ares_status_t ares_buf_tag_fetch_constbuf(const ares_buf_t *buf, + ares_buf_t **newbuf); + +/*! Consume the given number of bytes without reading them. + * + * \param[in] buf Initialized buffer object + * \param[in] len Length to consume + * \return ARES_SUCCESS or one of the c-ares error codes + */ +CARES_EXTERN ares_status_t ares_buf_consume(ares_buf_t *buf, size_t len); + +/*! Fetch a 16bit Big Endian number from the buffer. + * + * \param[in] buf Initialized buffer object + * \param[out] u16 Buffer to hold 16bit integer + * \return ARES_SUCCESS or one of the c-ares error codes + */ +CARES_EXTERN ares_status_t ares_buf_fetch_be16(ares_buf_t *buf, + unsigned short *u16); + +/*! Fetch a 32bit Big Endian number from the buffer. + * + * \param[in] buf Initialized buffer object + * \param[out] u32 Buffer to hold 32bit integer + * \return ARES_SUCCESS or one of the c-ares error codes + */ +CARES_EXTERN ares_status_t ares_buf_fetch_be32(ares_buf_t *buf, + unsigned int *u32); + + +/*! Fetch the requested number of bytes into the provided buffer + * + * \param[in] buf Initialized buffer object + * \param[out] bytes Buffer to hold data + * \param[in] len Requested number of bytes (must be > 0) + * \return ARES_SUCCESS or one of the c-ares error codes + */ +CARES_EXTERN ares_status_t ares_buf_fetch_bytes(ares_buf_t *buf, + unsigned char *bytes, + size_t len); + + +/*! Fetch the requested number of bytes and return a new buffer that must be + * ares_free()'d by the caller. + * + * \param[in] buf Initialized buffer object + * \param[in] len Requested number of bytes (must be > 0) + * \param[in] null_term Even though this is considered binary data, the user + * knows it may be a vald string, so add a null + * terminator. + * \param[out] bytes Pointer passed by reference. Will be allocated. + * \return ARES_SUCCESS or one of the c-ares error codes + */ +CARES_EXTERN ares_status_t ares_buf_fetch_bytes_dup(ares_buf_t *buf, size_t len, + ares_bool_t null_term, + unsigned char **bytes); + +/*! Fetch the requested number of bytes and place them into the provided + * dest buffer object. + * + * \param[in] buf Initialized buffer object + * \param[out] dest Buffer object to append bytes. + * \param[in] len Requested number of bytes (must be > 0) + * \return ARES_SUCCESS or one of the c-ares error codes + */ +CARES_EXTERN ares_status_t ares_buf_fetch_bytes_into_buf(ares_buf_t *buf, + ares_buf_t *dest, + size_t len); + +/*! Fetch the requested number of bytes and return a new buffer that must be + * ares_free()'d by the caller. The returned buffer is a null terminated + * string. The data is validated to be ASCII-printable. + * + * \param[in] buf Initialized buffer object + * \param[in] len Requested number of bytes (must be > 0) + * \param[out] str Pointer passed by reference. Will be allocated. + * \return ARES_SUCCESS or one of the c-ares error codes + */ +CARES_EXTERN ares_status_t ares_buf_fetch_str_dup(ares_buf_t *buf, size_t len, + char **str); + +/*! Consume whitespace characters (0x09, 0x0B, 0x0C, 0x0D, 0x20, and optionally + * 0x0A). + * + * \param[in] buf Initialized buffer object + * \param[in] include_linefeed ARES_TRUE to include consuming 0x0A, + * ARES_FALSE otherwise. + * \return number of whitespace characters consumed + */ +CARES_EXTERN size_t ares_buf_consume_whitespace(ares_buf_t *buf, + ares_bool_t include_linefeed); + + +/*! Consume any non-whitespace character (anything other than 0x09, 0x0B, 0x0C, + * 0x0D, 0x20, and 0x0A). + * + * \param[in] buf Initialized buffer object + * \return number of characters consumed + */ +CARES_EXTERN size_t ares_buf_consume_nonwhitespace(ares_buf_t *buf); + + +/*! Consume until a character in the character set provided is reached. Does + * not include the character from the charset at the end. + * + * \param[in] buf Initialized buffer object + * \param[in] charset character set + * \param[in] len length of character set + * \param[in] require_charset require we find a character from the charset. + * if ARES_FALSE it will simply consume the + * rest of the buffer. If ARES_TRUE will return + * SIZE_MAX if not found. + * \return number of characters consumed + */ +CARES_EXTERN size_t ares_buf_consume_until_charset(ares_buf_t *buf, + const unsigned char *charset, + size_t len, + ares_bool_t require_charset); + + +/*! Consume until a sequence of bytes is encountered. Does not include the + * sequence of characters itself. + * + * \param[in] buf Initialized buffer object + * \param[in] seq sequence of bytes + * \param[in] len length of sequence + * \param[in] require_charset require we find the sequence. + * if ARES_FALSE it will simply consume the + * rest of the buffer. If ARES_TRUE will return + * SIZE_MAX if not found. + * \return number of characters consumed + */ +CARES_EXTERN size_t ares_buf_consume_until_seq(ares_buf_t *buf, + const unsigned char *seq, + size_t len, + ares_bool_t require_seq); + +/*! Consume while the characters match the characters in the provided set. + * + * \param[in] buf Initialized buffer object + * \param[in] charset character set + * \param[in] len length of character set + * \return number of characters consumed + */ +CARES_EXTERN size_t ares_buf_consume_charset(ares_buf_t *buf, + const unsigned char *charset, + size_t len); + + +/*! Consume from the current position until the end of the line, and optionally + * the end of line character (0x0A) itself. + * + * \param[in] buf Initialized buffer object + * \param[in] include_linefeed ARES_TRUE to include consuming 0x0A, + * ARES_FALSE otherwise. + * \return number of characters consumed + */ +CARES_EXTERN size_t ares_buf_consume_line(ares_buf_t *buf, + ares_bool_t include_linefeed); + +typedef enum { + /*! No flags */ + ARES_BUF_SPLIT_NONE = 0, + /*! The delimiter will be the first character in the buffer, except the + * first buffer since the start doesn't have a delimiter. This option is + * incompatible with ARES_BUF_SPLIT_LTRIM since the delimiter is always + * the first character. + */ + ARES_BUF_SPLIT_KEEP_DELIMS = 1 << 0, + /*! Allow blank sections, by default blank sections are not emitted. If using + * ARES_BUF_SPLIT_KEEP_DELIMS, the delimiter is not counted as part + * of the section */ + ARES_BUF_SPLIT_ALLOW_BLANK = 1 << 1, + /*! Remove duplicate entries */ + ARES_BUF_SPLIT_NO_DUPLICATES = 1 << 2, + /*! Perform case-insensitive matching when comparing values */ + ARES_BUF_SPLIT_CASE_INSENSITIVE = 1 << 3, + /*! Trim leading whitespace from buffer */ + ARES_BUF_SPLIT_LTRIM = 1 << 4, + /*! Trim trailing whitespace from buffer */ + ARES_BUF_SPLIT_RTRIM = 1 << 5, + /*! Trim leading and trailing whitespace from buffer */ + ARES_BUF_SPLIT_TRIM = (ARES_BUF_SPLIT_LTRIM | ARES_BUF_SPLIT_RTRIM) +} ares_buf_split_t; + +/*! Split the provided buffer into multiple sub-buffers stored in the variable + * pointed to by the linked list. The sub buffers are const buffers pointing + * into the buf provided. + * + * \param[in] buf Initialized buffer object + * \param[in] delims Possible delimiters + * \param[in] delims_len Length of possible delimiters + * \param[in] flags One more more flags + * \param[in] max_sections Maximum number of sections. Use 0 for + * unlimited. Useful for splitting key/value + * pairs where the delimiter may be a valid + * character in the value. A value of 1 would + * have little usefulness and would effectively + * ignore the delimiter itself. + * \param[out] arr Result. Depending on flags, this may be a + * valid array with no elements. Use + * ares_array_destroy() to free the memory which + * will also free the contained ares_buf_t * + * objects. Each buf object returned by + * ares_array_at() or similar is a pointer to + * an ares_buf_t * object, meaning you need to + * accept it as "ares_buf_t **" then dereference. + * \return ARES_SUCCESS on success, or error like ARES_ENOMEM. + */ +CARES_EXTERN ares_status_t ares_buf_split( + ares_buf_t *buf, const unsigned char *delims, size_t delims_len, + ares_buf_split_t flags, size_t max_sections, ares_array_t **arr); + +/*! Split the provided buffer into an ares_array_t of C strings. + * + * \param[in] buf Initialized buffer object + * \param[in] delims Possible delimiters + * \param[in] delims_len Length of possible delimiters + * \param[in] flags One more more flags + * \param[in] max_sections Maximum number of sections. Use 0 for + * unlimited. Useful for splitting key/value + * pairs where the delimiter may be a valid + * character in the value. A value of 1 would + * have little usefulness and would effectively + * ignore the delimiter itself. + * \param[out] arr Array of strings. Free using + * ares_array_destroy(). + * \return ARES_SUCCESS on success, or error like ARES_ENOMEM. + */ +CARES_EXTERN ares_status_t ares_buf_split_str_array( + ares_buf_t *buf, const unsigned char *delims, size_t delims_len, + ares_buf_split_t flags, size_t max_sections, ares_array_t **arr); + +/*! Split the provided buffer into a C array of C strings. + * + * \param[in] buf Initialized buffer object + * \param[in] delims Possible delimiters + * \param[in] delims_len Length of possible delimiters + * \param[in] flags One more more flags + * \param[in] max_sections Maximum number of sections. Use 0 for + * unlimited. Useful for splitting key/value + * pairs where the delimiter may be a valid + * character in the value. A value of 1 would + * have little usefulness and would effectively + * ignore the delimiter itself. + * \param[out] strs Array of strings. Free using + * ares_free_array(strs, nstrs, ares_free) + * \param[out] nstrs Number of elements in the array. + * \return ARES_SUCCESS on success, or error like ARES_ENOMEM. + */ +CARES_EXTERN ares_status_t ares_buf_split_str( + ares_buf_t *buf, const unsigned char *delims, size_t delims_len, + ares_buf_split_t flags, size_t max_sections, char ***strs, size_t *nstrs); + +/*! Check the unprocessed buffer to see if it begins with the sequence of + * characters provided. + * + * \param[in] buf Initialized buffer object + * \param[in] data Bytes of data to compare. + * \param[in] data_len Length of data to compare. + * \return ARES_TRUE on match, ARES_FALSE otherwise. + */ +CARES_EXTERN ares_bool_t ares_buf_begins_with(const ares_buf_t *buf, + const unsigned char *data, + size_t data_len); + + +/*! Size of unprocessed remaining data length + * + * \param[in] buf Initialized buffer object + * \return length remaining + */ +CARES_EXTERN size_t ares_buf_len(const ares_buf_t *buf); + +/*! Retrieve a pointer to the currently unprocessed data. Generally this isn't + * recommended to be used in practice. The returned pointer may be invalidated + * by any future ares_buf_*() calls. + * + * \param[in] buf Initialized buffer object + * \param[out] len Length of available data + * \return Pointer to buffer of unprocessed data + */ +CARES_EXTERN const unsigned char *ares_buf_peek(const ares_buf_t *buf, + size_t *len); + +/*! Retrieve the next byte in the buffer without moving forward. + * + * \param[in] buf Initialized buffer object + * \param[out] b Single byte + * \return \return ARES_SUCCESS on success, or error + */ +CARES_EXTERN ares_status_t ares_buf_peek_byte(const ares_buf_t *buf, + unsigned char *b); + +/*! Wipe any processed data from the beginning of the buffer. This will + * move any remaining data to the front of the internally allocated buffer. + * + * Can not be used on const buffer objects. + * + * Typically not needed to call, as any new append operation will automatically + * call this function if there is insufficient space to append the data in + * order to try to avoid another memory allocation. + * + * It may be useful to call in order to ensure the current message being + * processed is in the beginning of the buffer if there is an intent to use + * ares_buf_set_position() and ares_buf_get_position() as may be necessary + * when processing DNS compressed names. + * + * If there is an active tag, it will NOT clear the tag, it will use the tag + * as the start of the unprocessed data rather than the current offset. If + * a prior tag is no longer needed, may be wise to call ares_buf_tag_clear(). + * + * \param[in] buf Initialized buffer object + */ +CARES_EXTERN void ares_buf_reclaim(ares_buf_t *buf); + +/*! Set the current offset within the internal buffer. + * + * Typically this should not be used, if possible, use the ares_buf_tag*() + * operations instead. + * + * One exception is DNS name compression which may backwards reference to + * an index in the message. It may be necessary in such a case to call + * ares_buf_reclaim() if using a dynamic (non-const) buffer before processing + * such a message. + * + * \param[in] buf Initialized buffer object + * \param[in] idx Index to set position + * \return ARES_SUCCESS if valid index + */ +CARES_EXTERN ares_status_t ares_buf_set_position(ares_buf_t *buf, size_t idx); + +/*! Get the current offset within the internal buffer. + * + * Typically this should not be used, if possible, use the ares_buf_tag*() + * operations instead. + * + * This can be used to get the current position, useful for saving if a + * jump via ares_buf_set_position() is performed and need to restore the + * current position for future operations. + * + * \param[in] buf Initialized buffer object + * \return index of current position + */ +CARES_EXTERN size_t ares_buf_get_position(const ares_buf_t *buf); + +/*! Parse a character-string as defined in RFC1035, as a null-terminated + * string. + * + * \param[in] buf initialized buffer object + * \param[in] remaining_len maximum length that should be used for parsing + * the string, this is often less than the remaining + * buffer and is based on the RR record length. + * \param[out] name Pointer passed by reference to be filled in with + * allocated string of the parsed that must be + * ares_free()'d by the caller. + * \return ARES_SUCCESS on success + */ +CARES_EXTERN ares_status_t ares_buf_parse_dns_str(ares_buf_t *buf, + size_t remaining_len, + char **name); + +/*! Parse a character-string as defined in RFC1035, as binary, however for + * convenience this does guarantee a NULL terminator (that is not included + * in the returned length). + * + * \param[in] buf initialized buffer object + * \param[in] remaining_len maximum length that should be used for parsing + * the string, this is often less than the remaining + * buffer and is based on the RR record length. + * \param[out] bin Pointer passed by reference to be filled in with + * allocated string of the parsed that must be + * ares_free()'d by the caller. + * \param[out] bin_len Length of returned string. + * \return ARES_SUCCESS on success + */ +CARES_EXTERN ares_status_t ares_buf_parse_dns_binstr(ares_buf_t *buf, + size_t remaining_len, + unsigned char **bin, + size_t *bin_len); + +/*! Load data from specified file path into provided buffer. The entire file + * is loaded into memory. + * + * \param[in] filename complete path to file + * \param[in,out] buf Initialized (non-const) buffer object to load data + * into + * \return ARES_ENOTFOUND if file not found, ARES_EFILE if issues reading + * file, ARES_ENOMEM if out of memory, ARES_SUCCESS on success. + */ +CARES_EXTERN ares_status_t ares_buf_load_file(const char *filename, + ares_buf_t *buf); + +/*! @} */ + +#endif /* __ARES__BUF_H */ |