Multi String and CSV functions
[Utilities]


Defines

#define KHM_PREFIX   8
#define KHM_CASE_SENSITIVE   16
#define KHM_MAXCCH_STRING   16384
#define KHM_MAXCB_STRING   (KHM_MAXCCH_STRING * sizeof(wchar_t))

Functions

KHMEXP khm_int32 KHMAPI multi_string_init (wchar_t *ms, khm_size cb_ms)
 Initialize a multi-string.
KHMEXP khm_int32 KHMAPI multi_string_prepend (wchar_t *ms, khm_size *pcb_ms, const wchar_t *str)
 Prepend a string to a multi string.
KHMEXP khm_int32 KHMAPI multi_string_append (wchar_t *ms, khm_size *pcb_ms, const wchar_t *str)
 Append a string to a multi-string.
KHMEXP khm_int32 KHMAPI multi_string_delete (wchar_t *ms, const wchar_t *str, const khm_int32 flags)
 Deletes a string from a multi string.
KHMEXP wchar_t *KHMAPI multi_string_find (const wchar_t *ms, const wchar_t *str, const khm_int32 flags)
 Search a multi string for a string.
KHMEXP khm_int32 KHMAPI multi_string_to_csv (wchar_t *csvbuf, khm_size *pcb_csvbuf, const wchar_t *ms)
 Convert a multi string to CSV.
KHMEXP khm_int32 KHMAPI csv_to_multi_string (wchar_t *ms, khm_size *pcb_ms, const wchar_t *csv)
 Converts a CSV to a multi string.
KHMEXP wchar_t *KHMAPI multi_string_next (const wchar_t *str)
 Get the next string in a multi string.
KHMEXP khm_int32 KHMAPI multi_string_length_cb (const wchar_t *str, khm_size max_cb, khm_size *len_cb)
 Get the length of a multi string in bytes.
KHMEXP khm_int32 KHMAPI multi_string_length_cch (const wchar_t *str, khm_size max_cch, khm_size *len_cch)
 Get the length of a multi string in characters.
KHMEXP khm_size KHMAPI multi_string_length_n (const wchar_t *str)
 Get the number of strings in a multi string.
KHMEXP khm_int32 KHMAPI multi_string_copy_cb (wchar_t *s_dest, khm_size max_cb_dest, const wchar_t *src)
 Copy a multi string with byte counts.
KHMEXP khm_int32 KHMAPI multi_string_copy_cch (wchar_t *s_dest, khm_size max_cch_dest, const wchar_t *src)
 Copy a multi string with character count.


Function Documentation

KHMEXP khm_int32 KHMAPI csv_to_multi_string ( wchar_t *  ms,
khm_size pcb_ms,
const wchar_t *  csv 
)

Converts a CSV to a multi string.

Undoes what multi_string_to_csv() does.

Parameters:
[out] ms The buffer that recieves the multi string. This can be NULL if only the size of the buffer is requried.
[in,out] pcb_ms On entry contains the number of bytes ni the buffer poitned to by ms. On exit contains the number of bytes that were copied to ms including terminating NULLs, or if the buffer was too small or ms was NULL, holds the size in bytes of the requied buffer.
[in] csv The CSV string.
Return values:
KHM_ERROR_SUCCESS The CSV string was successfully converted. The number of bytes written is in pcb_ms.
KHM_ERROR_TOO_LONG The provided buffer was too small or ms was NULL. The required size of the buffer in bytes is in pcb_ms.
KHM_ERROR_INVALID_PARAM One or more parameters were invalid.

KHMEXP khm_int32 KHMAPI multi_string_append ( wchar_t *  ms,
khm_size pcb_ms,
const wchar_t *  str 
)

Append a string to a multi-string.

Appends the string specified by str to the multi string specified by ms. The size of the multi string in characters including terminating NULLs after appending str can not exceed KHM_MAXCCH_STRING.

Parameters:
[in] ms The buffer containing the multi string
[in,out] pcb_ms Points to a khm_int32 indicating the size of the buffer pointed to by ms. On entry this contains the size (in bytes) of the buffer pointed to by ms. On exit, contains the new size of the multi string in bytes.
[in] str The string to append to the multi string. This string cannot be NULL or an empty (zero length) string. The length of str cannot exceed KHM_MAXCCH_STRING in characters including terminating NULL.
Return values:
KHM_ERROR_SUCCESS The string was appended to the multi string
KHM_ERROR_TOO_LONG The buffer pointed to by ms was insufficient. The required size of the buffer is in pcb_ms
KHM_ERROR_INVALID_PARAM One of more of the parameters were invalid.

KHMEXP khm_int32 KHMAPI multi_string_copy_cb ( wchar_t *  s_dest,
khm_size  max_cb_dest,
const wchar_t *  src 
)

Copy a multi string with byte counts.

Copy a multi string from one location to another.

Parameters:
[out] s_dest Receives a copy of the multi string
[in] max_cb_dest Number of bytes in the buffer pointed to by s_dest.
[in] src The source multi string
Return values:
KHM_ERROR_SUCCESS The multi string was copied successfully
KHM_ERROR_INVALID_PARAM One or more parameters were invalid.
KHM_ERROR_TOO_LONG The size of the destination buffer was insufficient.

KHMEXP khm_int32 KHMAPI multi_string_copy_cch ( wchar_t *  s_dest,
khm_size  max_cch_dest,
const wchar_t *  src 
)

Copy a multi string with character count.

Copy a multi string from one location to another.

Parameters:
[out] s_dest Receives a copy of the multi string
[in] max_cb_dest Number of characters in the buffer pointed to by s_dest.
[in] src The source multi string
Return values:
KHM_ERROR_SUCCESS The multi string was copied successfully
KHM_ERROR_INVALID_PARAM One or more parameters were invalid.
KHM_ERROR_TOO_LONG The size of the destination buffer was insufficient.

KHMEXP khm_int32 KHMAPI multi_string_delete ( wchar_t *  ms,
const wchar_t *  str,
const khm_int32  flags 
)

Deletes a string from a multi string.

Deletes the string specified by str from the multi string specified by ms. How the string is matched to the strings in ms is determined by flags. If more than one match is found, then only the first match is deleted.

Parameters:
[in] ms The multi string to modify. The length of the multi string in characters cannot exceed KHM_MAXCCH_STRING.
[in] str The string to search for
[in] flags How str is to be matched to existing strings in ms. This could be a combination of KHM_PREFIX and KHM_CASE_SENSITIVE. If KHM_PREFIX is used, then ms is searched for a string that begins with str. Otherwise, str must match the an entire string in the multi string. If KHM_CASE_SENSITIVE is specified, then a case sensitive match is performed. The defualt is to use a case insensitive search.
Return values:
KHM_ERROR_SUCCESS A string was matched and deleted from ms
KHM_ERROR_NOT_FOUND No matches were found
KHM_ERROR_INVALID_PARAM One or more parameters were incorrect.
Note:
The search for the existing string is done with multi_string_find()

KHMEXP wchar_t* KHMAPI multi_string_find ( const wchar_t *  ms,
const wchar_t *  str,
const khm_int32  flags 
)

Search a multi string for a string.

Searches the string specified by ms for a string that matches str. How the match is performed is determined by flags. Returns a poitner to the start of the matched string in ms. If more than one string in ms matches str, then only the first match is returned.

Parameters:
[in] ms The multi string to search in. The length of the multi string cannot exceed KHM_MAXCCH_STRING in characters.
[in] str The string to search for
[in] flags How str is to be matched to existing strings in ms. This could be a combination of KHM_PREFIX and KHM_CASE_SENSITIVE. If KHM_PREFIX is used, then ms is searched for a string that begins with str. Otherwise, str must match the an entire string in the multi string. If KHM_CASE_SENSITIVE is specified, then a case sensitive match is performed. The defualt is to use a case insensitive search.
Returns:
A pointer to the start of the first matched string or NULL if no matches were found.

KHMEXP khm_int32 KHMAPI multi_string_length_cb ( const wchar_t *  str,
khm_size  max_cb,
khm_size len_cb 
)

Get the length of a multi string in bytes.

The returned length includes the trailing double NULL and any other NULL inbetween.

Parameters:
[in] str Pointer to a multi string.
[in] max_cb Maximum size that the str can be. This can not be larger than KHM_MAXCB_STRING.
[out] len_cb The length of the string in bytes if the call is successful.
Return values:
KHM_ERROR_SUCCESS The length of the string is in len_cb
KHM_ERROR_INVALID_PARAM One or more parameters were invalid
KHM_ERROR_TOO_LONG The multi string is longer than max_cb bytes.

KHMEXP khm_int32 KHMAPI multi_string_length_cch ( const wchar_t *  str,
khm_size  max_cch,
khm_size len_cch 
)

Get the length of a multi string in characters.

The returned length includes the trailing double NULL and any other NULL inbetween.

Parameters:
[in] str Pointer to a multi string.
[in] max_cch Maximum size that the str can be. This can not be larger than KHM_MAXCCH_STRING.
[out] len_cch The length of the string in characters if the call is successful.
Return values:
KHM_ERROR_SUCCESS The length of the string is in len_cch
KHM_ERROR_INVALID_PARAM One or more parameters were invalid
KHM_ERROR_TOO_LONG The multi string is longer than max_cch characters.

KHMEXP wchar_t* KHMAPI multi_string_next ( const wchar_t *  str  ) 

Get the next string in a multi string.

When str is pointing to a string that is in a multi string, this function returns a pointer to the next string in the multi string.

Typically, one would start by having str point to the start of the multi string (which is the first string in the multi string), and then call this function repeatedly, until it returns NULL, at which point the end of the multi string has been reached.

Parameters:
[in] str Pointer to a string in a multi string. Each string in a multi string cannot exceed KHM_MAXCCH_STRING in charaters including the terminating NULL.
Returns:
A pointer to the start of the next string in the multi string or NULL if there is no more strings.

KHMEXP khm_int32 KHMAPI multi_string_prepend ( wchar_t *  ms,
khm_size pcb_ms,
const wchar_t *  str 
)

Prepend a string to a multi string.

Adds the string str to the beginning of multi-string ms.

Parameters:
[in,out] ms The multi-string to be modified.
[in,out] pcb_ms A pointer to the size of the multistring. On entry this specifies the size of the buffer pointed to by ms. If the call is successful, on exit this will receive the new size of the multi string in bytes. If the buffer is insufficient, the function will return KHM_ERROR_TOO_LONG and set this to the required size of the buffer in bytes.
[in] str The string to prepend to ms. This cannot be longer than KHM_MAXCCH_STRING in characters including the terminating NULL.

KHMEXP khm_int32 KHMAPI multi_string_to_csv ( wchar_t *  csvbuf,
khm_size pcb_csvbuf,
const wchar_t *  ms 
)

Convert a multi string to CSV.

Converts a multi string to a comma separated value string based on the following rules.

For example:

    multi_string = L"foo\0bar\0baz,quux\0ab\"cd\0";
    csv_string = L"foo,bar,\"baz,quux\",\"ab\"\"cd\"";

If multi_string_to_csv() is called on multi_string above, you would obtain csv_string.

Parameters:
[out] csvbuf The buffer to place the CSV string in. Can be NULL if only teh size of the needed buffer is required.
[in,out] pcb_csvbuf On entry, points to a khm_int32 that holds the size of the buffer pointed to by csvbuf. On exit, gets the number of bytes writted to csvbuf or the required size of csvbuf if the buffer is too small or csvbuf is NULL.
[in] ms The mutli string to convert to a CSV.
Return values:
KHM_ERROR_SUCCESS The multi string was successfully converted to a CSV string. The number of bytes written is in pcb_csvbuf. The count includes the terminating NULL.
KHM_ERROR_TOO_LONG The buffer was too small or csvbuf was NULL. The required number of bytes in the buffer is in pcb_csvbuf.
KHM_ERROR_INVALID_PARAM One or more parameters were ivnalid.
See also:
csv_to_multi_string()


Generated on Fri Aug 3 08:27:14 2007 for Network Identity Manager by Doxygen 1.5.2
© 2004-2007 Massachusetts Institute of Technology.
© 2005-2007 Secure Endpoints Inc.
Contact khimaira@mit.edu