VCSAgEncodeString
int VCSAgEncodeString(VCSAgEncodingType from_encoding,
void *input_string, int input_string_length,
VCSAgEncodingType to_encoding,
void **output_string, int *output_string_length)
where VCSAgEncodingType is an enumerated data type defined as:
enum VCSAgEncodingType {
VCSAgUTF8, /* UTF-8 encoding */
VCSAgUCS2, /* UCS-2 encoding */
VCSAgStr /* OS encoding */
};
This primitive is used to encode a string from one encoding format to another. The encoding formats are limited to UTF-8 and the default OS encoding formats for UNIX agents.
This API allocates the required amount of memory for the output encoded string. The caller is responsible for freeing this memory. The function stores a pointer to the encoded string in the variable "output_string" and sets "ouput_string_length" to the number of characters (ASCII or UCS-2) in this newly encoded string.
The return values of this primitive are 0 on success, 1 on failure.
This API is needed as part of the localization changes in the agent framework. The agent entry points written in C++ receive the arguments in UTF-8 encoding format. If the entry points need the localized values for these arguments, they must convert the arguments, using the VCSAgEncodeString API, into the OS_encoding or the UCS-2 encoding format.
Currently, the VCS engine does not accept localized values as input for arguments. Also, any output captured from the script entry points run in a locale other than "C" are converted into the UTF-8 encoding format by the agent framework and logged in the VCS engine log, also in the UTF-8 encoding format. To view the output in the appropriate locale, use the hamsg utility. Please refer to the VCS User's Guide for more on the hasmg utility.
Example: VCSAgEncodeString
//
// The example shows how the primitive VCSAgEncodeString can
// be used in the agent.
//
//
// A function used in the agent to convert a given string in UTF-8
// encoding to the OS-encoding. Its a wrapper around the primitive
// VCSAgEncodeString.
//
char* ConvertToOSEncoding(const char *utf8_string)
{
int len = 0, out_string_len;
char *out_string = NULL;
len = strlen(utf8_string);
VCSAgEncodeString(VCSAgUTF8, /* convert from UTF8 */
(void *)utf8_string,
len,
VCSAgStr, /* to the OS encoding format */
(void **)&out_string,
&out_string_len);
return out_string;
}
VCSAgResState res_monitor(const char *res_name, void **attr_val,
int *conf_level_ptr)
{ ...
char *os_encoded_string = NULL;
...
//
// Memory for os_encoded_string is allocated in the agent
// framework primitive VCSAgEncodeString
//
os_encoded_string = ConvertToOSEncoding((const char *)attr_val[0]);
...
// Free the memory allocated to os_encoded_string
if (os_encoded_string) {
delete[] os_encoded_string;
os_encoded_string = NULL;
}
...
}
VCSAgStrlcpy
void VCSAgStrlcpy(CHAR *dst, const CHAR *src, int size)
This primitive copies the contents from the input buffer "src" to the output buffer "dst" up to a maximum of "size" number of characters. Here, "size" refers to the size of the output buffer "dst." This helps prevent any buffer overflow errors. The output contained in the buffer "dst" may be truncated if the buffer is not big enough.
VCSAgStrlcat
void VCSAgStrlcat(CHAR *dst, const CHAR *src, int size)
This primitive concatenates the contents of the input buffer "src" to the contents of the output buffer "dst" up to a maximum such that the total number of characters in the buffer "dst" do not exceed the value of "size." Here, "size" refers to the size of the output buffer "dst."
This helps prevent any buffer overflow errors. The output contained in the buffer "dst" may be truncated if the buffer is not big enough.
VCSAgSnprintf
int VCSAgSnprintf(CHAR *dst, int size, const char *format, ...)
This primitive accepts a variable number of arguments and works just like the C library function "sprintf." The difference is that this primitive takes in, as an argument, the size of the output buffer "dst." The primitive stores only a maximum of "size" number of characters in the output buffer "dst." This helps prevent any buffer overflow errors. The output contained in the buffer "dst" may be truncated if the buffer is not big enough.
|
