Managing Parallels Service Preferences

Parallels Service preferences is a set of parameters that control its default behaviour. Some of the important parameters are:

• Memory limits for the Parallels Service itself.
• Memory limits and recommended values for virtual machines.
• Virtual network adapter information.
• Default virtual machine directory (the directory where all new virtual machines are created by default).
• Communication security level.

Parallels Service preferences are managed using the PHT_DISP_CONFIG handle which is obtained using the PrlSrv_GetCommonPrefs function. For the complete list of functions provided by the PHT_DISP_CONFIG object, see the Parallels C API Reference guide.

The following sample function demonstrates how to obtain a handle of type PHT_DISP_CONFIG and how to use its functions to retrieve and modify some of the Parallels Service preferences. The function accepts the hServer parameter which is a server handle. For the example on how to obtain a server handle, see Obtaining Server Handle and Logging In .

PRL_RESULT GetSetServicePrefs(PRL_HANDLE hServer)

{

// Variables for handles.

PRL_HANDLE hJob = PRL_INVALID_HANDLE;

PRL_HANDLE hJobResult = PRL_INVALID_HANDLE;

PRL_HANDLE hDispConfig = PRL_INVALID_HANDLE;

// Variables for return codes.

PRL_RESULT ret = PRL_ERR_UNINITIALIZED;

PRL_RESULT nJobReturnCode = PRL_ERR_UNINITIALIZED;

// An asynchronous call that obtains a handle

// of type PHT_DISP_CONFIG.

hJob = PrlSrv_GetCommonPrefs(hServer);

// Wait for the job to complete.

ret = PrlJob_Wait(hJob, 1000);

if (PRL_FAILED(ret))

{

// Handle the error...

PrlHandle_Free(hJob);

return -1;

}

// Analyze the result of PrlSrv_GetCommonPrefs.

ret = PrlJob_GetRetCode(hJob, &nJobReturnCode);

if (PRL_FAILED(ret))

{

// Handle the error...

PrlHandle_Free(hJob);

return -1;

}

// Get the job return code.

if (PRL_FAILED(nJobReturnCode))

{

// Handle the error...

PrlHandle_Free(hJob);

return -1;

}

// Get job result.

ret = PrlJob_GetResult(hJob, &hJobResult);

PrlHandle_Free(hJob);

if (PRL_FAILED(ret))

{

// Handle the error...

return -1;

}

// Get the PHT_DISP_CONFIG handle.

ret = PrlResult_GetParam(hJobResult, &hDispConfig);

PrlHandle_Free(hJobResult);

if (PRL_FAILED(ret))

{

// Handle the error...

return -1;

}

// Get the default virtual machine directory.

char sDefaultDir[1024];

PRL_UINT32 nBufSize = sizeof(sDefaultDir);

ret = PrlDispCfg_GetDefaultVmDir(hDispConfig,

sDefaultDir, &nBufSize);

if (PRL_FAILED(ret))

{

fprintf(stderr, "Error: %s\n",

prl_result_to_string(ret));

PrlHandle_Free(hDispConfig);

return -1;

}

printf("Parallels Service Preferences \n\n");

printf("Default VM Directory: %s\n", sDefaultDir);

// Get the recommended virtual machine memory size.

PRL_UINT32 nMemSize = 0;

ret = PrlDispCfg_GetRecommendMaxVmMem(hDispConfig, &nMemSize);

if (PRL_FAILED(ret))

{

fprintf(stderr, "Error: %s\n",

prl_result_to_string(ret));

PrlHandle_Free(hDispConfig);

return -1;

}

printf("Recommended VM memory size: %d\n", nMemSize);

// Modify some of the Parallels Service preferences.

// Begin edit.

hJob = PrlSrv_CommonPrefsBeginEdit(hServer);

ret = PrlJob_Wait(hJob, 1000);

if (PRL_FAILED(ret))

{

fprintf(stderr, "Error: %s\n",

prl_result_to_string(ret));

PrlHandle_Free(hJob);

PrlHandle_Free(hDispConfig);

return -1;

}

// Get the "begin edit" operation success code.

ret = PrlJob_GetRetCode(hJob, &nJobReturnCode);

if (PRL_FAILED(ret))

{

fprintf(stderr, "Error: %s\n",

prl_result_to_string(ret));

PrlHandle_Free(hJob);

PrlHandle_Free(hDispConfig);

return -1;

}

if (PRL_FAILED(nJobReturnCode))

{

fprintf(stderr, "Error: %s\n",

prl_result_to_string(nJobReturnCode));

PrlHandle_Free(hJob);

PrlHandle_Free(hDispConfig);

return -1;

}

PrlHandle_Free(hJob);

// Modify the recommended virtual machine memory size.

nMemSize = 512;

ret = PrlDispCfg_SetRecommendMaxVmMem(hDispConfig, nMemSize);

if (PRL_FAILED(ret))

{

fprintf(stderr, "Error: %s\n",

prl_result_to_string(ret));

PrlHandle_Free(hDispConfig);

return -1;

}

// Commit the changes.

hJob = PrlSrv_CommonPrefsCommit(hServer, hDispConfig);

ret = PrlJob_Wait(hJob, 1000);

if (PRL_FAILED(ret))

{

fprintf(stderr, "Error: %s\n",

prl_result_to_string(ret));

PrlHandle_Free(hJob);

PrlHandle_Free(hDispConfig);

return -1;

}

ret = PrlJob_GetRetCode(hJob, &nJobReturnCode);

if (PRL_FAILED(ret))

{

fprintf(stderr, "Error: %s\n",

prl_result_to_string(ret));

PrlHandle_Free(hJob);

PrlHandle_Free(hDispConfig);

return -1;

}

if (PRL_FAILED(nJobReturnCode))

{

fprintf(stderr, "Error: %s\n",

prl_result_to_string(nJobReturnCode));

PrlHandle_Free(hJob);

PrlHandle_Free(hDispConfig);

return -1;

}

printf("The recommended VM memory size changed to: %d\n", nMemSize);

PrlHandle_Free(hDispConfig);

return 0;

}