Character String Conversion Functions

Functions
int	rtValidateStr (ASN1TAG tag, const char *pdata)
int	rtValidateChars (ASN1TAG tag, const char *pdata, size_t nchars)
const char *	rtBMPToCString (ASN1BMPString *pBMPString, char *cstring, OSSIZE cstrsize)
const char *	rtBMPToNewCString (ASN1BMPString *pBMPString)
const char *	rtBMPToNewCStringEx (OSCTXT *pctxt, ASN1BMPString *pBMPString)
ASN1BMPString *	rtCToBMPString (OSCTXT *pctxt, const char *cstring, ASN1BMPString *pBMPString, Asn116BitCharSet *pCharSet)
OSBOOL	rtIsIn16BitCharSet (OSUNICHAR ch, Asn116BitCharSet *pCharSet)
const char *	rtUCSToCString (ASN1UniversalString *pUCSString, char *cstring, OSSIZE cstrsize)
const char *	rtUCSToNewCString (ASN1UniversalString *pUCSString)
const char *	rtUCSToNewCStringEx (OSCTXT *pctxt, ASN1UniversalString *pUCSString)
ASN1UniversalString *	rtCToUCSString (OSCTXT *pctxt, const char *cstring, ASN1UniversalString *pUCSString, Asn132BitCharSet *pCharSet)
OSBOOL	rtIsIn32BitCharSet (OS32BITCHAR ch, Asn132BitCharSet *pCharSet)
wchar_t *	rtUCSToWCSString (ASN1UniversalString *pUCSString, wchar_t *wcstring, OSUINT32 wcstrsize)
ASN1UniversalString *	rtWCSToUCSString (OSCTXT *pctxt, wchar_t *wcstring, ASN1UniversalString *pUCSString, Asn132BitCharSet *pCharSet)
int	rtUnivStrToUTF8 (OSCTXT *pctxt, const ASN1UniversalString *pUnivStr, OSOCTET *outbuf, size_t outbufsiz)
int	rtUTF8StrToASN1DynBitStr (OSCTXT *pctxt, const OSUTF8CHAR *utf8str, ASN1DynBitStr *pvalue)
int	rtUTF8StrnToASN1DynBitStr (OSCTXT *pctxt, const OSUTF8CHAR *utf8str, size_t nbytes, ASN1DynBitStr *pvalue)

Detailed Description

Common utility functions are provided to convert between standard null-terminated C strings and different ASN.1 string types.

Function Documentation

rtBMPToCString()

const char* rtBMPToCString	(	ASN1BMPString *	pBMPString,
		char *	cstring,
		OSSIZE	cstrsize
	)

This function converts a BMP string into a null-terminated C string. Any characters that are not 8-bit characters are discarded.

Parameters

pBMPString	A pointer to a BMP string structure to be converted.
cstring	A pointer to a buffer to receive the converted string.
cstrsize	The size of the buffer to receive the converted string.

Returns

A pointer to the returned string structure. This is the cstring argument parameter value.

rtBMPToNewCString()

const char* rtBMPToNewCString

(

ASN1BMPString *

pBMPString

)

This function converts a BMP string into a null-terminated C string. Any characters that are not 8-bit characters are discarded. This function allocates dynamic memory to hold the converted string using the standard C run-time malloc function. The user is responsible for freeing this memory.

Parameters

pBMPString

A pointer to a BMP string structure to be converted.

Returns

A pointer to the returned string structure. This is the cstring argument parameter value.

rtBMPToNewCStringEx()

const char* rtBMPToNewCStringEx	(	OSCTXT *	pctxt,
		ASN1BMPString *	pBMPString
	)

This function converts a BMP string into a null-terminated C string. Any characters that are not 8-bit characters are discarded. In contrast to rtBMPToNewCString, this function allocates dynamic memory to hold the converted string using the rtMemAlloc function. The rtMemFreePtr should be called to release the allocated memory or the rtmemFree function should be called to release all memory allocated using the specified context block.

Parameters

pctxt	A pointer to a context structure.
pBMPString	A pointer to a BMP string structure to be converted.

Returns

A pointer to the returned string structure. This is the cstring argument parameter value.

rtCToBMPString()

ASN1BMPString* rtCToBMPString	(	OSCTXT *	pctxt,
		const char *	cstring,
		ASN1BMPString *	pBMPString,
		Asn116BitCharSet *	pCharSet
	)

This function converts a null-terminated C string into a 16-bit BMP string structure.

Parameters

pctxt	A pointer to a context string.
cstring	A pointer to a null-terminated C string to be converted into a BMP string.
pBMPString	A pointer to a BMP string structure to receive the converted string.
pCharSet	A pointer to a character set structure describing the character set currently associated with the BMP character string type.

Returns

A pointer to BMP string structure. This is the pBMPString argument parameter value.

rtCToUCSString()

ASN1UniversalString* rtCToUCSString	(	OSCTXT *	pctxt,
		const char *	cstring,
		ASN1UniversalString *	pUCSString,
		Asn132BitCharSet *	pCharSet
	)

This function converts a null-terminated C string into a 32-bit UCS-4 (Universal Character Set, 4 byes) string structure.

Parameters

pctxt	A pointer to a context structure.
cstring	A pointer to a null-terminated C string to be converted into a Universal string.
pUCSString	A pointer to a Universal string structure to receive the converted string
pCharSet	A pointer to a character structure describing the character set currently associated with the Universal character string type.

Returns

A pointer to a Universal string structure. This is the pUCSString argument parameter value.

rtIsIn16BitCharSet()

OSBOOL rtIsIn16BitCharSet	(	OSUNICHAR	ch,
		Asn116BitCharSet *	pCharSet
	)

This function tests whether the given character is in the given 16-bit character set.

Parameters

ch	A 16-bit character.
pCharSet	A pointer-to Asn116BitCharSet that contains the set of valid character.

Returns

TRUE if the character is in the set, FALSE otherwise.

rtIsIn32BitCharSet()

OSBOOL rtIsIn32BitCharSet	(	OS32BITCHAR	ch,
		Asn132BitCharSet *	pCharSet
	)

This function tests whether the given character is in the given 32-bit character set.

Parameters

ch	A 32-bit character.
pCharSet	A pointer-to Asn132BitCharSet that contains the set of valid character.

Returns

TRUE if the character is in the set, FALSE otherwise.

rtUCSToCString()

const char* rtUCSToCString	(	ASN1UniversalString *	pUCSString,
		char *	cstring,
		OSSIZE	cstrsize
	)

This function converts a Universal 32-bit string into a null-terminated C string. Any characters that are not 8-bit characters are discarded.

Parameters

pUCSString	A pointer to a Universal string structure to be converted.
cstring	A pointer to a buffer to receive a converted string.
cstrsize	The size of the buffer to receive the converted string.

Returns

The pointer to the returned string. This is the cstring argument parameter value.

rtUCSToNewCString()

const char* rtUCSToNewCString

(

ASN1UniversalString *

pUCSString

)

This function converts a Universal 32-bit string into a null-terminated C string. Any characters that are not 8-bit characters are discarded. This function allocates dynamic memory to hold the converted string using the standard C run-time malloc function. The user is responsible for freeing this memory.

Parameters

pUCSString

A pointer to a Universal 32-bit string structure to be converted.

Returns

A pointer to allocated null-terminated string. The user is responsible for freeing this memory.

rtUCSToNewCStringEx()

const char* rtUCSToNewCStringEx	(	OSCTXT *	pctxt,
		ASN1UniversalString *	pUCSString
	)

This function converts a Universal 32-bit string into a null-terminated C string. Any characters that are not 8-bit characters are discarded. In contrast to rtUSCToNewCString this function allocates dynamic memory to hold the converted string using the rtMemAlloc function. The rtMemFreePtr should be called to release the allocated memory or the rtMemFree function should be called to release all memory allocated using the specified context block.

Parameters

pctxt	A pointer to a context block.
pUCSString	A pointer to a Universal 32-bit string structure to be converted.

Returns

A pointer to allocated null-terminated string. The user is responsible for freeing this memory.

rtUCSToWCSString()

wchar_t* rtUCSToWCSString	(	ASN1UniversalString *	pUCSString,
		wchar_t *	wcstring,
		OSUINT32	wcstrsize
	)

This function converts a 32-bits encoded string to a wide character string.

Parameters

pUCSString	A pointer to a Universal string structure.
wcstring	The pointer to the buffer to receive the converted string.
wcstrsize	The number of wide characters (wchar_t) the outbuffer can hold.

Returns

A character count or error status. This will be negative if the conversion fails. If the result is positive, the number of characters was written to scstrsize.

rtUnivStrToUTF8()

int rtUnivStrToUTF8	(	OSCTXT *	pctxt,
		const ASN1UniversalString *	pUnivStr,
		OSOCTET *	outbuf,
		size_t	outbufsiz
	)

This function converts an ASN.1 Universal String type (32-bit characters) to UTF-8.

Parameters

pctxt	A pointer to a context structure.
pUnivStr	Pointer to universal string to be converted.
outbuf	Output buffer to receive UTF-8 characters.
outbufsiz	Output buffer size in bytes.

Returns

Zero if conversion was successful, a negative status code if failed.

rtUTF8StrnToASN1DynBitStr()

int rtUTF8StrnToASN1DynBitStr	(	OSCTXT *	pctxt,
		const OSUTF8CHAR *	utf8str,
		size_t	nbytes,
		ASN1DynBitStr *	pvalue
	)

This function converts the given part of UTF-8 string to a bit string value. The string consists of a series of '1' and '0' characters. This is the dynamic version in which memory is allocated for the returned binary string variable. Bits are stored from MSB to LSB order.

Parameters

pctxt	Pointer to context block structure.
utf8str	UTF-8 string to convert. Not necessary to be null-terminated.
nbytes	Size in bytes of utf8Str.
pvalue	Pointer to a variable to receive the decoded boolean value.

Returns

Completion status of operation:

• 0 = success,
• negative return value is error.

rtUTF8StrToASN1DynBitStr()

int rtUTF8StrToASN1DynBitStr	(	OSCTXT *	pctxt,
		const OSUTF8CHAR *	utf8str,
		ASN1DynBitStr *	pvalue
	)

This function converts the given null-terminated UTF-8 string to a bit string value. The string consists of a series of '1' and '0' characters. This is the dynamic version in which memory is allocated for the returned binary string variable. Bits are stored from MSB to LSB order.

Parameters

pctxt	Pointer to context block structure.
utf8str	Null-terminated UTF-8 string to convert
pvalue	Pointer to a variable to receive the decoded boolean value.

Returns

Completion status of operation:

• 0 = success,
• negative return value is error.

rtValidateChars()

int rtValidateChars	(	ASN1TAG	tag,
		const char *	pdata,
		size_t	nchars
	)

This function ensures that a given string does not contain invalid characters.

Parameters

tag	The ASN.1 Tag that identifies the string.
pdata	A pointer to the character string to be examined.
nchars	The number of characters in pdata.

Returns

This function returns 0 if the string validates or the tag is not associated with a string; it otherwise returns the integer value of the character that invalidates the string.

rtValidateStr()

int rtValidateStr	(	ASN1TAG	tag,
		const char *	pdata
	)

This function ensures that a given string does not contain invalid characters.

Parameters

tag	The ASN.1 Tag that identifies the string.
pdata	A pointer to the character string to be examined.

Returns

This function returns 0 if the string validates or the tag is not associated with a string; it otherwise returns the integer value of the character that invalidates the string.

rtWCSToUCSString()

ASN1UniversalString* rtWCSToUCSString	(	OSCTXT *	pctxt,
		wchar_t *	wcstring,
		ASN1UniversalString *	pUCSString,
		Asn132BitCharSet *	pCharSet
	)

This function converts a wide-character string to a Universal 32-bits encoded string.

Parameters

pctxt	A pointer to a context structure.
wcstring	The pointer to the wide-character (Unicode) string to convert
pUCSString	The pointer to the Universal String structure to receive the converted string.
pCharSet	The pointer to the character set structure describing the character set currently associated with the Universal character string type.

Returns

If the conversion of the WCS to the UTF-8 was successful, the number of bytes in the converted string is returned. If the encoding fails, a negative status value is returned.