Character String Conversion Functions
[C Runtime Common 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, OSUINT32 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, OSUINT32 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

const char* rtBMPToCString ( ASN1BMPString *  pBMPString,
char *  cstring,
OSUINT32  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.
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.
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.
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.
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.
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.
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.
const char* rtUCSToCString ( ASN1UniversalString *  pUCSString,
char *  cstring,
OSUINT32  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.
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.
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.
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.
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.
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.
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.
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.
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.
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.