Registry-Based Conversions

There are two categories of conversion, as discussed in the design. Single conversion, and bulk conversion. The single conversions only do one unit of indivisible work. The bulk functions repeatedly perform one unit of indivisible work.

`cnc_conversion` Conversion Functions

The conversion functions are split into single conversion (contains a _one in the name), which perform one unit of indivisible work, and those that are “multi” conversions (without the _one in the name), which do it in bulk. There is also some functions to check the status of the

bool cnc_conv_state_is_complete(const cnc_conversion *__conversion)

Checks if any associated stored state has no outstanding data left.

Parameters: __conversion – [in] The cnc_conversion handle to check for state completion. Shall not be nullptr.

Single Conversion Functions

cnc_mcerr cnc_conv_one_pivot(cnc_conversion *__conversion, size_t *__p_output_bytes_size, unsigned char **__p_output_bytes, size_t *__p_input_bytes_size, const unsigned char **__p_input_bytes, cnc_pivot_info *__p_pivot_info)

Peforms at least one complete unit of work on the input and produces one complete unit of work into the output according to the format of __conversion.

Remark

This function only performs exactly one complete unit of work for the input and the output: nothing more. The conversion functions take parameters as output parameters (pointers) so that they can provide information about how much of the input and output is used. Providing a nullptr for both __p_ouput_bytes_size and __p_output_bytes serves as a way to validate the input for one completely unit of work. Providing only __p_output_bytes but not __p_output_bytes_size is a way to indicate that the output space is sufficiently large for the input space. Providing __p_output_bytes_size but not __p_output_bytes is a way to determine how much data will be written out for a given input without actually performing such a write.

Parameters

__conversion – [in] The cnc_conversion handle indicating the format to be used. Shall not be nullptr.
__p_output_bytes_size – [inout] A pointer to the size of the output buffer. If this is nullptr, then it will not update the count (and the output stream will automatically be considered large enough to handle all data, if __p_output_bytes is not nullptr).
__p_output_bytes – [inout] A pointer to the pointer of the output buffer. If this or the pointer within are nullptr, than this function will not write output data (it may still decrement the value pointed to by __p_output_bytes_size).
__p_input_bytes_size – [inout] A pointer to the size of the input buffer. If this is nullptr or points to a value equivalent to 0, then the input is considered empty and cnc_mcerr_ok is returned.
__p_input_bytes – [inout] A pointer to the pointer of the input buffer. If this or the pointer within are nullptr, than the input is considered empty and cnc_mcerr_ok is returned.
__p_pivot_info – [inout] A pointer to a pivot buffer and return error code. If the return value of this function is not cnc_mcerr_ok, the pivot information is not NULL, and the error was caused by the intermediate conversion step failing, then the error member of cnc_pivot_info will be set to the error value that took place.

cnc_mcerr cnc_conv_one(cnc_conversion *__conversion, size_t *__p_output_bytes_size, unsigned char **__p_output_bytes, size_t *__p_input_bytes_size, const unsigned char **__p_input_bytes)

Peforms at least one complete unit of work on the input and produces one complete unit of work into the output according to the format of __conversion.

Remark

This function only performs exactly one complete unit of work for the input and the output: nothing more. The conversion functions take parameters as output parameters (pointers) so that they can provide information about how much of the input and output is used. Providing a nullptr for both __p_ouput_bytes_size and __p_output_bytes serves as a way to validate the input for one completely unit of work. Providing only __p_output_bytes but not __p_output_bytes_size is a way to indicate that the output space is sufficiently large for the input space. Providing __p_output_bytes_size but not __p_output_bytes is a way to determine how much data will be written out for a given input without actually performing such a write.

Parameters

__conversion – [in] The cnc_conversion handle indicating the format to be used. Shall not be nullptr.
__p_output_bytes_size – [inout] A pointer to the size of the output buffer. If this is nullptr, then it will not update the count (and the output stream will automatically be considered large enough to handle all data, if __p_output_bytes is not nullptr).
__p_output_bytes – [inout] A pointer to the pointer of the output buffer. If this or the pointer within are nullptr, than this function will not write output data (it may still decrement the value pointed to by __p_output_bytes_size).
__p_input_bytes_size – [inout] A pointer to the size of the input buffer. If this is nullptr or points to a value equivalent to 0, then the input is considered empty and cnc_mcerr_ok is returned.
__p_input_bytes – [inout] A pointer to the pointer of the input buffer. If this or the pointer within are nullptr, than the input is considered empty and cnc_mcerr_ok is returned.

cnc_mcerr cnc_conv_one_count_pivot(cnc_conversion *__conversion, size_t *__p_output_bytes_size, size_t *__p_input_bytes_size, const unsigned char **__p_input_bytes, cnc_pivot_info *__p_pivot_info)

Counts the total number of bytes that can be successfully converted for one complete unit of input, or if an error occurs, for the specified __conversion format.

Remark

This function is an ease-of-use shortcut for calling cnc_conv_one with the __p_output_bytes argument sent to nullptr.

Parameters

__conversion – [in] The cnc_conversion handle indicating the format to be used. Shall not be nullptr.
__p_output_bytes_size – [inout] A pointer to the size of the output buffer. If this is nullptr, then it will not update the count.
__p_input_bytes_size – [inout] A pointer to the size of the input buffer. If this is nullptr or points to a value equivalent to 0, then the input is considered empty and cnc_mcerr_ok is returned.
__p_input_bytes – [inout] A pointer to the pointer of the input buffer. If this or the pointer within are nullptr, than the input is considered empty and cnc_mcerr_ok is returned.
__p_pivot_info – [inout] A pointer to a pivot buffer and return error code. If the return value of this function is not cnc_mcerr_ok, the pivot information is not NULL, and the error was caused by the intermediate conversion step failing, then the error member of cnc_pivot_info will be set to the error value that took place.

cnc_mcerr cnc_conv_one_count(cnc_conversion *__conversion, size_t *__p_output_bytes_size, size_t *__p_input_bytes_size, const unsigned char **__p_input_bytes)

Counts the total number of bytes that can be successfully converted for one complete unit of input, or if an error occurs, for the specified __conversion format.

Remark

This function is an ease-of-use shortcut for calling cnc_conv_one with the __p_output_bytes argument sent to nullptr.

Parameters

__conversion – [in] The cnc_conversion handle indicating the format to be used. Shall not be nullptr.
__p_output_bytes_size – [inout] A pointer to the size of the output buffer. If this is nullptr, then it will not update the count.
__p_input_bytes_size – [inout] A pointer to the size of the input buffer. If this is nullptr or points to a value equivalent to 0, then the input is considered empty and cnc_mcerr_ok is returned.
__p_input_bytes – [inout] A pointer to the pointer of the input buffer. If this or the pointer within are nullptr, than the input is considered empty and cnc_mcerr_ok is returned.

bool cnc_conv_one_is_valid_pivot(cnc_conversion *__conversion, size_t *__p_input_bytes_size, const unsigned char **__p_input_bytes, cnc_pivot_info *__p_pivot_info)

Checks whether or not one complete unit of input can be successfully converted according to the format of __conversion to one complete unit of output.

Remark

This function is an ease-of-use shortcut for calling cnc_conv_one with the __p_output_bytes argument and the __out_pput_byte_size argument set to nullptr sent to nullptr.

Parameters

__conversion – [in] The cnc_conversion handle indicating the format to be used. Shall not be nullptr.
__p_input_bytes_size – [inout] A pointer to the size of the input buffer. If this is nullptr or points to a value equivalent to 0, then the input is considered empty and true is returned.
__p_input_bytes – [inout] A pointer to the pointer of the input buffer. If this or the pointer within are nullptr, than the input is considered empty and true is returned.
__p_pivot_info – [inout] A pointer to a pivot buffer and return error code. If the return value of this function is not cnc_mcerr_ok, the pivot information is not NULL, and the error was caused by the intermediate conversion step failing, then the error member of cnc_pivot_info will be set to the error value that took place.

bool cnc_conv_one_is_valid(cnc_conversion *__conversion, size_t *__p_input_bytes_size, const unsigned char **__p_input_bytes)

Checks whether or not one complete unit of input can be successfully converted according to the format of __conversion to one complete unit of output.

Remark

This function is an ease-of-use shortcut for calling cnc_conv_one with the __p_output_bytes argument and the __out_pput_byte_size argument set to nullptr sent to nullptr.

Parameters

__conversion – [in] The cnc_conversion handle indicating the format to be used. Shall not be nullptr.
__p_input_bytes_size – [inout] A pointer to the size of the input buffer. If this is nullptr or points to a value equivalent to 0, then the input is considered empty and true is returned.
__p_input_bytes – [inout] A pointer to the pointer of the input buffer. If this or the pointer within are nullptr, than the input is considered empty and true is returned.

cnc_mcerr cnc_conv_one_unbounded_pivot(cnc_conversion *__conversion, unsigned char **__p_output_bytes, size_t *__p_input_bytes_size, const unsigned char **__p_input_bytes, cnc_pivot_info *__p_pivot_info)

Performs a conversion to the specified sequences, assuming that there is an appropriately sized buffer that will fit all of the output, no matter what.

Remark

This function is an ease-of-use shortcut for calling cnc_conv_one with the __p_output_bytes argument and the __out_pput_byte_size argument set to nullptr sent to nullptr.

Parameters

__conversion – [in] The cnc_conversion handle indicating the format to be used. Shall not be nullptr.
__p_output_bytes – [inout] A pointer to the pointer of the output buffer. If this or the pointer within are nullptr, than this function will not write output data (it may still decrement the value pointed to by __p_output_bytes_size).
__p_input_bytes_size – [inout] A pointer to the size of the input buffer. If this is nullptr or points to a value equivalent to 0, then the input is considered empty and true is returned.
__p_input_bytes – [inout] A pointer to the pointer of the input buffer. If this or the pointer within are nullptr, than the input is considered empty and true is returned.
__p_pivot_info – [inout] A pointer to a pivot buffer and return error code. If the return value of this function is not cnc_mcerr_ok, the pivot information is not NULL, and the error was caused by the intermediate conversion step failing, then the error member of cnc_pivot_info will be set to the error value that took place.

cnc_mcerr cnc_conv_one_unbounded(cnc_conversion *__conversion, unsigned char **__p_output_bytes, size_t *__p_input_bytes_size, const unsigned char **__p_input_bytes)

Performs a conversion to the specified sequences, assuming that there is an appropriately sized buffer that will fit all of the output, no matter what.

Remark

This function is an ease-of-use shortcut for calling cnc_conv_one with the __p_output_bytes argument and the __out_pput_byte_size argument set to nullptr sent to nullptr.

Parameters

__conversion – [in] The cnc_conversion handle indicating the format to be used. Shall not be nullptr.
__p_output_bytes – [inout] A pointer to the pointer of the output buffer. If this or the pointer within are nullptr, than this function will not write output data (it may still decrement the value pointed to by __p_output_bytes_size).
__p_input_bytes_size – [inout] A pointer to the size of the input buffer. If this is nullptr or points to a value equivalent to 0, then the input is considered empty and true is returned.
__p_input_bytes – [inout] A pointer to the pointer of the input buffer. If this or the pointer within are nullptr, than the input is considered empty and true is returned.

Multi (“Bulk”) Conversion Functions

cnc_mcerr cnc_conv_pivot(cnc_conversion *__conversion, size_t *__p_output_bytes_size, unsigned char **__p_output_bytes, size_t *__p_input_bytes_size, const unsigned char **__p_input_bytes, cnc_pivot_info *__p_pivot_info)

Converts a series of bytes in one encoding scheme to the other encoding scheme using the specified __conversion format.

Remark

The conversion functions take parameters as output parameters (pointers) so that they can provide information about how much of the input and output is used. Providing a nullptr for both __p_ouput_bytes_size and __p_output_bytes serves as a way to validate the input. Providing only __p_output_bytes but not __p_output_bytes_size is a way to indicate that the output space is sufficiently large for the input space. Providing __p_output_bytes_size but not __p_output_bytes is a way to determine how much data will be written out for a given input without actually performing such a write. The pivot buffer is used when the conversion cannot be done directly (which is specified through the cnc_conversion_info structure returned from opening a conversion routine). If the pivot buffer does not point to a null / empty buffer, and it ends up being too small for the given conversion, it may produce spurious cnc_mcerr_insufficient_output errors unrelated to the actual __p_output_bytes buffer passed into the function.

Parameters

__conversion – [in] The cnc_conversion handle indicating the format to be used. Shall not be nullptr.
__p_output_bytes_size – [inout] A pointer to the size of the output buffer. If this is nullptr, then it will not update the count (and the output stream will automatically be considered large enough to handle all data, if __p_output_bytes is not nullptr).
__p_output_bytes – [inout] A pointer to the pointer of the output buffer. If this or the pointer within are nullptr, than this function will not write output data (it may still decrement the value pointed to by __p_output_bytes_size).
__p_input_bytes_size – [inout] A pointer to the size of the input buffer. If this is nullptr or points to a value equivalent to 0, then the input is considered empty and cnc_mcerr_ok is returned.
__p_input_bytes – [inout] A pointer to the pointer of the input buffer. If this or the pointer within are nullptr, than the input is considered empty and cnc_mcerr_ok is returned.
__p_pivot_info – [inout] A pointer to a pivot buffer and return error code. If the return value of this function is not cnc_mcerr_ok, the pivot information is not NULL, and the error was caused by the intermediate conversion step failing, then the error member of cnc_pivot_info will be set to the error value that took place.

cnc_mcerr cnc_conv(cnc_conversion *__conversion, size_t *__p_output_bytes_size, unsigned char **__p_output_bytes, size_t *__p_input_bytes_size, const unsigned char **__p_input_bytes)

Converts a series of bytes in one encoding scheme to the other encoding scheme using the specified __conversion format.

Remark

The conversion functions take parameters as output parameters (pointers) so that they can provide information about how much of the input and output is used. Providing a nullptr for both __p_ouput_bytes_size and __p_output_bytes serves as a way to validate the input. Providing only __p_output_bytes but not __p_output_bytes_size is a way to indicate that the output space is sufficiently large for the input space. Providing __p_output_bytes_size but not __p_output_bytes is a way to determine how much data will be written out for a given input without actually performing such a write.

Parameters

__conversion – [in] The cnc_conversion handle indicating the format to be used. Shall not be nullptr.
__p_output_bytes_size – [inout] A pointer to the size of the output buffer. If this is nullptr, then it will not update the count (and the output stream will automatically be considered large enough to handle all data, if __p_output_bytes is not nullptr).
__p_output_bytes – [inout] A pointer to the pointer of the output buffer. If this or the pointer within are nullptr, than this function will not write output data (it may still decrement the value pointed to by __p_output_bytes_size).
__p_input_bytes_size – [inout] A pointer to the size of the input buffer. If this is nullptr or points to a value equivalent to 0, then the input is considered empty and cnc_mcerr_ok is returned.
__p_input_bytes – [inout] A pointer to the pointer of the input buffer. If this or the pointer within are nullptr, than the input is considered empty and cnc_mcerr_ok is returned.

cnc_mcerr cnc_conv_count_pivot(cnc_conversion *__conversion, size_t *__p_output_bytes_size, size_t *__p_input_bytes_size, const unsigned char **__p_input_bytes, cnc_pivot_info *__p_pivot_info)

Counts the total number of bytes that can be successfully converted until an error occurs for the specified __conversion format.

Remark

This function is an ease-of-use shortcut for calling cnc_conv with the __p_output_bytes argument sent to nullptr.

Parameters

__conversion – [in] The cnc_conversion handle indicating the format to be used. Shall not be nullptr.
__p_output_bytes_size – [inout] A pointer to the size of the output buffer. If this is nullptr, then it will not update the count.
__p_input_bytes_size – [inout] A pointer to the size of the input buffer. If this is nullptr or points to a value equivalent to 0, then the input is considered empty and cnc_mcerr_ok is returned.
__p_input_bytes – [inout] A pointer to the pointer of the input buffer. If this or the pointer within are nullptr, than the input is considered empty and cnc_mcerr_ok is returned.
__p_pivot_info – [inout] A pointer to a pivot buffer and return error code. If the return value of this function is not cnc_mcerr_ok, the pivot information is not NULL, and the error was caused by the intermediate conversion step failing, then the error member of cnc_pivot_info will be set to the error value that took place.

cnc_mcerr cnc_conv_count(cnc_conversion *__conversion, size_t *__p_output_bytes_size, size_t *__p_input_bytes_size, const unsigned char **__p_input_bytes)

Counts the total number of bytes that can be successfully converted until an error occurs for the specified __conversion format.

Remark

This function is an ease-of-use shortcut for calling cnc_conv with the __p_output_bytes argument sent to nullptr.

Parameters

__conversion – [in] The cnc_conversion handle indicating the format to be used. Shall not be nullptr.
__p_output_bytes_size – [inout] A pointer to the size of the output buffer. If this is nullptr, then it will not update the count.
__p_input_bytes_size – [inout] A pointer to the size of the input buffer. If this is nullptr or points to a value equivalent to 0, then the input is considered empty and cnc_mcerr_ok is returned.
__p_input_bytes – [inout] A pointer to the pointer of the input buffer. If this or the pointer within are nullptr, than the input is considered empty and cnc_mcerr_ok is returned.

bool cnc_conv_is_valid_pivot(cnc_conversion *__conversion, size_t *__p_input_bytes_size, const unsigned char **__p_input_bytes, cnc_pivot_info *__p_pivot_info)

Checks whether or not the input can be successfully converted according to the format of __conversion.

Remark

This function is an ease-of-use shortcut for calling cnc_conv with the __p_output_bytes argument sent to nullptr.

Parameters

__conversion – [in] The cnc_conversion handle indicating the format to be used. Shall not be nullptr.
__p_input_bytes_size – [inout] A pointer to the size of the input buffer. If this is nullptr or points to a value equivalent to 0, then the input is considered empty and true is returned.
__p_input_bytes – [inout] A pointer to the pointer of the input buffer. If this or the pointer within are nullptr, than the input is considered empty and true is returned.
__p_pivot_info – [inout] A pointer to a pivot buffer and return error code. If the return value of this function is not cnc_mcerr_ok, the pivot information is not NULL, and the error was caused by the intermediate conversion step failing, then the error member of cnc_pivot_info will be set to the error value that took place.

bool cnc_conv_is_valid(cnc_conversion *__conversion, size_t *__p_input_bytes_size, const unsigned char **__p_input_bytes)

Checks whether or not the input can be successfully converted according to the format of __conversion.

Remark

This function is an ease-of-use shortcut for calling cnc_conv with the __p_output_bytes argument sent to nullptr.

Parameters

__conversion – [in] The cnc_conversion handle indicating the format to be used. Shall not be nullptr.
__p_input_bytes_size – [inout] A pointer to the size of the input buffer. If this is nullptr or points to a value equivalent to 0, then the input is considered empty and true is returned.
__p_input_bytes – [inout] A pointer to the pointer of the input buffer. If this or the pointer within are nullptr, than the input is considered empty and true is returned.

cnc_mcerr cnc_conv_unbounded_pivot(cnc_conversion *__conversion, unsigned char **__p_output_bytes, size_t *__p_input_bytes_size, const unsigned char **__p_input_bytes, cnc_pivot_info *__p_pivot_info)

Converts a series of bytes in one encoding scheme to the other encoding scheme using the specified __conversion format.

Remark

The conversion functions take parameters as output parameters (pointers) so that they can provide information about how much of the input and output is used. Providing a nullptr for both __p_ouput_bytes_size and __p_output_bytes serves as a way to validate the input. Providing only __p_output_bytes but not __p_output_bytes_size is a way to indicate that the output space is sufficiently large for the input space. Providing __p_output_bytes_size but not __p_output_bytes is a way to determine how much data will be written out for a given input without actually performing such a write.

Parameters

__conversion – [in] The cnc_conversion handle indicating the format to be used. Shall not be nullptr.
__p_output_bytes – [inout] A pointer to the pointer of the output buffer. If this or the pointer within are nullptr, than this function will not write output data (it may still decrement the value pointed to by __p_output_bytes_size).
__p_input_bytes_size – [inout] A pointer to the size of the input buffer. If this is nullptr or points to a value equivalent to 0, then the input is considered empty and cnc_mcerr_ok is returned.
__p_input_bytes – [inout] A pointer to the pointer of the input buffer. If this or the pointer within are nullptr, than the input is considered empty and cnc_mcerr_ok is returned.
__p_pivot_info – [inout] A pointer to a pivot buffer and return error code. If the return value of this function is not cnc_mcerr_ok, the pivot information is not NULL, and the error was caused by the intermediate conversion step failing, then the error member of cnc_pivot_info will be set to the error value that took place.

cnc_mcerr cnc_conv_unbounded(cnc_conversion *__conversion, unsigned char **__p_output_bytes, size_t *__p_input_bytes_size, const unsigned char **__p_input_bytes)

Converts a series of bytes in one encoding scheme to the other encoding scheme using the specified __conversion format.

Remark

The conversion functions take parameters as output parameters (pointers) so that they can provide information about how much of the input and output is used. Providing a nullptr for both __p_ouput_bytes_size and __p_output_bytes serves as a way to validate the input. Providing only __p_output_bytes but not __p_output_bytes_size is a way to indicate that the output space is sufficiently large for the input space. Providing __p_output_bytes_size but not __p_output_bytes is a way to determine how much data will be written out for a given input without actually performing such a write.

Parameters

__conversion – [in] The cnc_conversion handle indicating the format to be used. Shall not be nullptr.
__p_output_bytes – [inout] A pointer to the pointer of the output buffer. If this or the pointer within are nullptr, than this function will not write output data (it may still decrement the value pointed to by __p_output_bytes_size).
__p_input_bytes_size – [inout] A pointer to the size of the input buffer. If this is nullptr or points to a value equivalent to 0, then the input is considered empty and cnc_mcerr_ok is returned.
__p_input_bytes – [inout] A pointer to the pointer of the input buffer. If this or the pointer within are nullptr, than the input is considered empty and cnc_mcerr_ok is returned.

Registry-Based Conversions

cnc_conversion Conversion Functions

Single Conversion Functions

Multi (“Bulk”) Conversion Functions

`cnc_conversion` Conversion Functions