Strings as Return Values

Sting values in the Parallels C API are received by passing a char pointer to a function which populates it with data. It is the responsibility of the caller to allocate the memory required to receive the value, and to free it when it is no longer needed. Since in most cases we don't know the string size in advance, we have to either allocate a chunk of memory large enough for any possible value or to determine the exact required size. To determine the required buffer size, the following two approaches can be used:

1. Calling the same function twice: first, to obtain the required buffer size, and second, to receive the actual string value. To get the required buffer size, call the function passing a null pointer as a value of the output parameter, and pass 0 (zero) as a value of the variable that is used to specify the buffer size. The function will calculate the required size and will populate the variable with the correct value, which you can use to initialize a variable that will receive the string. You can then call the function again to get the actual string value.
2. It is also possible to use a static buffer. If the length of the buffer is large enough, you will simply receive the result. If the length is too small, a function will fail with the PRL_ERR_BUFFER_OVERRUN error but it will populate the "buffer_size" variable with the required size value. You can then allocate the memory using the received value and call the function again to get the results.

Consider the following API function:

PRL_RESULT PrlVmCfg_GetName(

PRL_HANDLE hVmCfg,

PRL_STR sVmName,

PRL_UINT32_PTR pnVmNameBufLength

);

The PrlVmCfg_GetName function above is a typical Parallels API function that returns a string value (in this case, the name of a virtual machine). The hVmCfg parameter is a handle to an object containing the virtual machine configuration information. The sVmName parameter is a char pointer. It is used as output that receives the virtual machine name. The variable must be initialized on the client side with enough memory allocated for the expected string. The size of the buffer must be specified using the pnVmNameBufLength variable.

The following example demonstrates how to call the function using the first approach:

PRL_RESULT ret;

PRL_UINT32 nBufSize = 0;

// Get the required buffer size.

ret = PrlVmCfg_GetName(hVmCfg, 0, &nBufSize);

// Allocate the memory.

PRL_STR pBuf = (PRL_STR)malloc(sizeof(PRL_CHAR) * nBufSize);

// Get the virtual machine name.

ret = PrlVmCfg_GetName(hVmCfg, pBuf, &nBufSize);

printf("VM name: %s\n", pBuf);

// Deallocate the memory.

free(pBuf);

The following example uses the second approach. To test the buffer-overrun scenario, set the sVmName array size to some small number.

#define MY_STR_BUF_SIZE 1024

PRL_RESULT ret;

char sVmName[MY_STR_BUF_SIZE];

PRL_UINT32 nBufSize = MY_STR_BUF_SIZE;

// Get the virtual machine name.

ret = PrlVmCfg_GetName(hVmCfg, sVmName, &nBufSize);

// Check for errors.

if ( PRL_SUCCEEDED (ret))

{

// Everything's OK, print the machine name.

printf("VM name: %s\n", sVmName);

}

else if (ret == PRL_ERR_BUFFER_OVERRUN)

{

// The sVmName array size is too small.

// Get the required size, allocate the memory,

// and try getting the VM name again.

PRL_UINT32 nSize = 0;

PRL_STR pBuf;

// Get the required buffer size.

ret = PrlVmCfg_GetName(hVmCfg, 0, &nSize);

// Allocate the memory.

pBuf = (PRL_STR)malloc(sizeof(PRL_CHAR) * nSize);

// Get the virtual machine name.

ret = PrlVmCfg_GetName(hVmCfg, pBuf, &nSize);

printf("VM name: %s\n", pBuf);

// Dallocate the memory.

free(pBuf);

}

Please send us your feedback on this help page