Retrieving Host Configuration Information

The Parallels C API provides a set of functions to retrieve detailed information about a host machine. This includes:

• CPU(s) - number of, mode, model, speed.
• Devices - disk drives, network interfaces, ports, sound.
• Operating system - type, version, etc.
• Memory (RAM) size.

This information can be used when modifying Parallels Service preferences, setting up devices inside virtual machines, or whenever you need to obtain information about the resources available on the physical host.

To retrieve this information, first obtain a handle of type PHT_SERVER_CONFIG and then use its functions to get information about a particular resource. The following sample function demonstrates how it is accomplished. 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 GetHostConfig(PRL_HANDLE hServer)

{

    PRL_HANDLE hJob = PRL_INVALID_HANDLE;

    PRL_HANDLE hJobResult = PRL_INVALID_HANDLE;

    PRL_HANDLE hHostConfig = PRL_INVALID_HANDLE;

    PRL_RESULT ret = PRL_ERR_UNINITIALIZED;

    PRL_RESULT nJobReturnCode = PRL_ERR_UNINITIALIZED;

    // An asynchronous call that obtains a handle

    // of type PHT_SERVER_CONFIG.

    hJob = PrlSrv_GetSrvConfig(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_GetSrvConfig.

    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_SERVER_CONFIG handle.

    ret = PrlResult_GetParam(hJobResult, &hHostConfig);

    PrlHandle_Free(hJobResult);

    if (PRL_FAILED(ret))

    {

        // Handle the error...

        return -1;

    }

    // Obtain the individual configuration setting.

    printf("\nHost Configuration Information: \n\n");

    // Get CPU count.

    PRL_UINT32 nCPUcount = 0;

    ret = PrlSrvCfg_GetCpuCount(hHostConfig, &nCPUcount);

    if (PRL_FAILED(ret))

    {

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

            prl_result_to_string(ret));

        PrlHandle_Free(hHostConfig);

        return -1;

    }    

    printf("CPUs: %d\n", nCPUcount);

    // Get host OS type.

    PRL_HOST_OS_TYPE nHostOsType;

    ret = PrlSrvCfg_GetHostOsType(hHostConfig, &nHostOsType);

    // if (PRL_FAILED(ret)) { handle the error... }

    printf("OS Type: %d\n", nHostOsType);

    // Get host RAM size.

    PRL_UINT32 nHostRamSize;

    ret = PrlSrvCfg_GetHostRamSize(hHostConfig, &nHostRamSize);

    // if (PRL_FAILED(ret)) { handle the error... }

    printf("RAM: %d MB\n", nHostRamSize);

    // Get the network adapter info.

    // First get the net adapter count.

    PRL_UINT32 nNetAdaptersCount = 0;

    ret = PrlSrvCfg_GetNetAdaptersCount(hHostConfig,

                                 &nNetAdaptersCount);

    // if (PRL_FAILED(ret)) { handle the error... }

    // Now iterate through the list and get the info

    // about each adapter.

    printf("\n");

    for (PRL_UINT32 i = 0; i < nNetAdaptersCount; ++i)

    {

        printf("Net Adapter %d\n", i+1);

        // Obtains a handle of type PHT_HW_NET_ADAPTER.

        PRL_HANDLE phDevice = PRL_INVALID_HANDLE;

        ret = PrlSrvCfg_GetNetAdapter(hHostConfig, i, &phDevice);

        // Get adapter type (physical, virtual).

        PRL_HW_INFO_NET_ADAPTER_TYPE nNetAdapterType;

        ret = PrlSrvCfgNet_GetNetAdapterType(phDevice,

                                    &nNetAdapterType);

        printf("Type: %d\n", nNetAdapterType);

        // Get system adapter index.

        PRL_UINT32 nIndex = 0;

        ret = PrlSrvCfgNet_GetSysIndex(phDevice, &nIndex);

        printf("Index: %d\n\n", nIndex);

    }

    PrlHandle_Free(hHostConfig);

    return 0;

}