Bridged Networking

Compared to host-only and shared network adapters, adding an adapter using bridged networking involves additional steps. In a bridged networking mode, you are binding the virtual adapter inside a virtual machine to an adapter on the host machine. Therefore, you first have to retrieve the list of adapters from the host and select the one you would like to use. The complete procedure of creating an adapter using bridged networking is as follows:

1. Obtain a list of network adapters installed on the host. This steps is preformed using the PrlSrvCfg_GetNetAdaptersCount, PrlSrvCfg_GetNetAdapter, and PrlSrvCfgDev_GetName functions.
2. Begin the virtual machine editing operation and create a new network adapter handle as described in the Host-only and Shared Networking section.
3. Bind the new virtual network adapter to the desired host machine adapter using the PrlVmDevNet_SetBoundAdapterName function.
4. Finalize the changes by calling the PrlVm_Commit function.

You can also bind a virtual network adapter to the default adapter on the host machine. In this case, you don't have to obtain the list of adapters from the host, so you can skip step 1 (above). In step 3, instead of setting the adapter name, set its index as -1 using the PrlVmDevNet_SetBoundAdapterIndex function.

The following are two sample functions that show the implementation of the steps described above. The two functions are similar except that the first one shows how to bind a virtual network adapter to a specific adapter on the host, whereas the second function shows how to bind the virtual adapter to the default host network adapter.

Example 1:

The function accepts a server handle and a virtual machine handle. The server handle will be used to obtain the list of network adapters from the host.

PRL_RESULT AddNetAdapterBridged(PRL_HANDLE hServer, PRL_HANDLE hVm)

{

    PRL_HANDLE hJob = PRL_INVALID_HANDLE;

    PRL_HANDLE hJobResult = PRL_INVALID_HANDLE;

    PRL_HANDLE hJobBeginEdit = PRL_INVALID_HANDLE;

    PRL_HANDLE hJobCommit = PRL_INVALID_HANDLE;

    PRL_HANDLE hVmCfg = PRL_INVALID_HANDLE;

    PRL_RESULT nJobRetCode = PRL_INVALID_HANDLE;

    PRL_UINT32 ret = PRL_ERR_UNINITIALIZED;

    // Obtain a list of the network adapters installed on

    // the host.

    // First, obtain a handle containing the

    // host configuration info.

    hJob = PrlSrv_GetSrvConfig(hServer);

    ret = PrlJob_Wait(hJob, 10000);

    PrlJob_GetRetCode(hJob, &nJobRetCode);

    if (PRL_FAILED(nJobRetCode))

    {

        // Handle the error.

    }

    // Get job results.

    ret = PrlJob_GetResult(hJob, &hJobResult);

    if (PRL_FAILED(ret))

    {

        // Handle the error.

    }

    // server config handle.        

    PRL_HANDLE hSrvCfg = PRL_INVALID_HANDLE;

    // counter.

    PRL_UINT32 nCount = PRL_INVALID_HANDLE;  

    // Now obtain the actual handle containing the

    // host configuration info.

    PrlResult_GetParam(hJobResult, &hSrvCfg);

    // Get the number of the available adapters from the

    // host configuration object.

    PrlSrvCfg_GetNetAdaptersCount(hSrvCfg, &nCount);

    // Net adapter handle.

    PRL_HANDLE hHostNetAdapter = PRL_INVALID_HANDLE;

    PRL_CHAR chHostAdapterName[1024];

    // Iterate through the list of the adapters.

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

    {

        PrlSrvCfg_GetNetAdapter(hSrvCfg, i, &hHostNetAdapter);

        // Get adapter name.

        PRL_CHAR chName[1024];

        PRL_UINT32 nBufSize = sizeof(chName);

        ret = PrlSrvCfgDev_GetName(hHostNetAdapter, chName, &nBufSize);

        // Normally, you would iterate through the entire list

        // and select an adapter to bind the virtual network adapter to.

        // For simplicity, we will simply pick the first one and use it.

        strcpy(chHostAdapterName, chName);

        break;

    }

    // Now that we have the name of the host network adapter,

    // we can add a new virtual network adapter to the virtual machine.

    // Timestamp the beginning of the configuration changes operation.

    // The hVm parameter specifies the target virtual machine.

    hJobBeginEdit = PrlVm_BeginEdit(hVm);

    ret = PrlJob_Wait(hJobBeginEdit, 10000);

    PrlJob_GetRetCode(hJobBeginEdit, &nJobRetCode);

    if (PRL_FAILED(nJobRetCode))

    {

        fprintf(stderr, "Error: %s\n", prl_result_to_string(nJobRetCode));

        PrlHandle_Free(hJobBeginEdit);

        return nJobRetCode;

    }

    // Obtain a handle of type PHT_VM_CONFIGURATION containing

    // the virtual machine configuration information.

    ret = PrlVm_GetConfig(hVm, &hVmCfg);

    if (PRL_FAILED(ret))

    {

        // Handle the error.

    }

    // Create a virtual network adapter device handle.

    PRL_HANDLE hNet = PRL_INVALID_HANDLE;

    ret = PrlVmCfg_CreateVmDev(

            hVmCfg, // The virtual machine configuration handle.

            PDE_GENERIC_NETWORK_ADAPTER, // Device type.

            &hNet); // Device handle.

    if (PRL_FAILED(ret))

    {

      // Handle the error.

    }

    // Set the virtual network adapter emulation type (networking type).

    // Bridged networking is set using the PDT_USE_BRIDGE_ETHERNET enumerator

    // from the PRL_VM_DEV_EMULATION_TYPE enumeration.

    ret = PrlVmDev_SetEmulatedType(hNet, PDT_USE_BRIDGE_ETHERNET);

    if (PRL_FAILED(ret))

    {

        // Handle the error.

    }

    // Set the host adapter to which this adapter should be bound.

    PrlVmDevNet_SetBoundAdapterName(hNet, chHostAdapterName);

    // By default, a new device is created disabled.

    // You can set the "connected" and "enabled" properties

    // as desired.

    PrlVmDev_SetConnected(hNet, PRL_TRUE);

    PrlVmDev_SetEnabled(hNet, PRL_TRUE);

    // Commit the changes.

    hJobCommit = PrlVm_Commit(hVm);

    ret = PrlJob_Wait(hJobBeginEdit, 10000);

    PrlJob_GetRetCode(hJobBeginEdit, &nJobRetCode);

    if (PRL_FAILED(nJobRetCode))

    {

        // Handle the error.

    }

    // Release all handles.

    PrlHandle_Free(hNet);

    PrlHandle_Free(hVmCfg);

    PrlHandle_Free(hJobBeginEdit);

    PrlHandle_Free(hJobCommit);

    return PRL_ERR_SUCCESS;

}

Example 2:

This function shows how to add a virtual network adapter to a virtual machine and how to bind it to the default adapter on the host.

PRL_RESULT AddNetAdapterBridgedDefault(PRL_HANDLE hVm)

{

    PRL_HANDLE hJobBeginEdit = PRL_INVALID_HANDLE;

    PRL_HANDLE hJobCommit = PRL_INVALID_HANDLE;

    PRL_HANDLE hVmCfg = PRL_INVALID_HANDLE;

    PRL_RESULT nJobRetCode = PRL_INVALID_HANDLE;

    PRL_UINT32 ret = PRL_ERR_UNINITIALIZED;

    // Timestamp the beginning of the configuration changes operation.

    // The hVm parameter specifies the target virtual machine.

    hJobBeginEdit = PrlVm_BeginEdit(hVm);

    ret = PrlJob_Wait(hJobBeginEdit, 10000);

    PrlJob_GetRetCode(hJobBeginEdit, &nJobRetCode);

    if (PRL_FAILED(nJobRetCode))

    {

        fprintf(stderr, "Error: %s\n", prl_result_to_string(nJobRetCode));

        PrlHandle_Free(hJobBeginEdit);

        return nJobRetCode;

    }

    // Obtain a handle of type PHT_VM_CONFIGURATION containing

    // the virtual machine configuration information.

    ret = PrlVm_GetConfig(hVm, &hVmCfg);

    if (PRL_FAILED(ret))

    {

        // Handle the error.

    }

    // Create a virtual network adapter device handle.

    PRL_HANDLE hNet = PRL_INVALID_HANDLE;

    ret = PrlVmCfg_CreateVmDev(

            hVmCfg, // The virtual machine configuration handle.

            PDE_GENERIC_NETWORK_ADAPTER, // Device type.

            &hNet); // Device handle.

    if (PRL_FAILED(ret))

    {

      // Handle the error.

    }

    // Set the virtual network adapter emulation type (networking type).

    // Bridged networking is set using the PDT_USE_BRIDGE_ETHERNET enumerator

    // from the PRL_VM_DEV_EMULATION_TYPE enumeration.

    ret = PrlVmDev_SetEmulatedType(hNet, PDT_USE_BRIDGE_ETHERNET );

    if (PRL_FAILED(ret))

    {

        // Handle the error.

    }

    // Set the host adapter index to -1. This will

    // bind the virtual adapter to the default adapter on the

    // host.

    PrlVmDevNet_SetBoundAdapterIndex(hNet, -1);

    // By default, a new device is created disabled.

    // You can set the "connected" and "enabled" properties

    // as desired.

    PrlVmDev_SetConnected(hNet, PRL_TRUE);

    PrlVmDev_SetEnabled(hNet, PRL_TRUE);

    // Commit the changes.

    hJobCommit = PrlVm_Commit(hVm);

    ret = PrlJob_Wait(hJobBeginEdit, 10000);

    PrlJob_GetRetCode(hJobBeginEdit, &nJobRetCode);

    if (PRL_FAILED(nJobRetCode))

    {

        // Handle the error.

    }

    // Release all handles.

    PrlHandle_Free(hNet);

    PrlHandle_Free(hVmCfg);

    PrlHandle_Free(hJobBeginEdit);

    PrlHandle_Free(hJobCommit);

    return PRL_ERR_SUCCESS;

}