BindExternalEthernetPort method of the Msvm_VirtualSwitchManagementService class
Binds an external Ethernet port to the Microsoft Windows Virtualization network subsystem. After this call is made, virtual machines can use the external Ethernet port to send data out over the physical network.
Syntax
uint32 BindExternalEthernetPort(
[in] Msvm_ExternalEthernetPort REF ExternalEthernetPort
);
Parameters
-
ExternalEthernetPort [in]
-
Type: Msvm_ExternalEthernetPort
A reference to the external Ethernet port to be bound. See Msvm_ExternalEthernetPort.
Return value
Type: uint32
The method returns 0 if it succeeded synchronously. Any other return value indicates an error.
-
Completed with No Error (0)
-
Method Parameters Checked - Job Started (4096)
-
Failed (32768)
-
Access Denied (32769)
-
Not Supported (32770)
-
Status is unknown (32771)
-
Timeout (32772)
-
Invalid parameter (32773)
-
System is in used (32774)
-
Invalid state for this operation (32775)
-
Incorrect data type (32776)
-
System is not available (32777)
-
Out of memory (32778)
Remarks
Access to the Msvm_VirtualSwitchManagementService class might be restricted by UAC Filtering. For more information, see User Account Control and WMI.
Examples
The following C# sample binds an external Ethernet port. The referenced utilities can be found in Common Utilities for the Virtualization Samples.
using System;
using System.Management;
namespace HyperVSamples
{
class BindExternalEthernetPortClass
{
static void BindExternalEthernetPort(string externalEthernetPortName)
{
ManagementScope scope = new ManagementScope(@"root\virtualization", null);
ManagementObject switchService = Utility.GetServiceObject(scope, "Msvm_VirtualSwitchManagementService");
ManagementObject externalEthernetPort = Utility.GetHostSystemDevice("Msvm_msvm_ExternalEthernetPort", externalEthernetPortName, scope);
ManagementBaseObject inParams = switchService.GetMethodParameters("BindExternalEthernetPort");
inParams["ExternalEthernetPort"] = externalEthernetPort.Path.Path;
ManagementBaseObject outParams = switchService.InvokeMethod("BindExternalEthernetPort", inParams, null);
if ((UInt32)outParams["ReturnValue"] == ReturnCode.Completed)
{
Console.WriteLine("{0} was bound successfully", externalEthernetPort["Name"]);
}
else
{
Console.WriteLine("Failed to bind {0} external Ethernet port.", externalEthernetPort["Name"]);
}
}
static void Main(string[] args)
{
if (args != null && args.Length != 2)
{
Console.WriteLine("Usage:\nBindExternalEthernetPort ExternalEthernetPortFriendlyName");
Console.WriteLine("Example:\nBindExternalEthernetPort \"Intel(R) PRO/1000 PM Network Connection\"");
return;
}
BindExternalEthernetPort(args[0]);
}
}
}
The following VBScript sample binds an external Ethernet port.
option explicit
dim objWMIService
dim switchService
dim fileSystem
const wmiSuccessful = 0
Main()
'-----------------------------------------------------------------
' Main
'-----------------------------------------------------------------
Sub Main()
dim computer, objArgs, externalEthernetPort, friendlyName
set objArgs = WScript.Arguments
if WScript.Arguments.Count = 1 then
friendlyName = objArgs.Unnamed.Item(0)
else
WScript.Echo "usage: cscript BindExternalEthernetPort ExternalEthernetPortFriendlyName"
WScript.Echo "Example: BindExternalEthernetPort ""Intel(R) PRO/1000 PM Network Connection"""
WScript.Quit(1)
end if
set fileSystem = Wscript.CreateObject("Scripting.FileSystemObject")
computer = "."
set objWMIService = GetObject("winmgmts:\\" & computer & "\root\virtualization")
set switchService = objWMIService.ExecQuery("select * from Msvm_VirtualSwitchManagementService").ItemIndex(0)
set externalEthernetPort = GetExternalEthernetPort(friendlyName)
if (externalEthernetPort Is Nothing) then
WriteLog Format1("Unable to find external Ethernet Port {0}", friendlyName)
WScript.Quit(1)
end if
if BindExternalEthernetPort(externalEthernetPort) then
WriteLog "Done"
WScript.Quit(0)
else
WriteLog("BindExternalEthernetPort failed")
WScript.Quit(1)
end if
End Sub
'-----------------------------------------------------------------
' Retrieve the external Ethernet port
'-----------------------------------------------------------------
Function GetExternalEthernetPort(externalEthernetPortFriendlyName)
dim objNTInfo, computerName, query, computer
dim externalEthernetPort, externalEthernetPorts
set GetExternalEthernetPort = Nothing
set objNTInfo = CreateObject("WinNTSystemInfo")
computerName = lcase(objNTInfo.ComputerName)
query = Format1("select * from Msvm_ComputerSystem where Name = '{0}'", computerName)
set computer = objWMIService.ExecQuery(query).ItemIndex(0)
query = Format1("ASSOCIATORS OF {{0}} WHERE resultClass = Msvm_ExternalEthernetPort", computer.Path_.Path)
set externalEthernetPorts = objWMIService.ExecQuery(query)
for each externalEthernetPort in externalEthernetPorts
if lcase(externalEthernetPort.ElementName) = lcase(externalEthernetPortFriendlyName) then
set GetExternalEthernetPort = externalEthernetPort
Exit Function
end if
next
End Function
'-----------------------------------------------------------------
' Bind the External Ethernet Port by calling BindExternalEthernetPort
'-----------------------------------------------------------------
Function BindExternalEthernetPort(externalEthernetPort)
dim objInParam, objOutParams
BindExternalEthernetPort = false
set objInParam = switchService.Methods_("BindExternalEthernetPort").InParameters.SpawnInstance_()
objInParam.ExternalEthernetPort = externalEthernetPort.Path_.Path
set objOutParams = switchService.ExecMethod_("BindExternalEthernetPort", objInParam)
if objOutParams.ReturnValue = wmiSuccessful then
BindExternalEthernetPort = true
else
WriteLog Format1("BindExternalEthernetPort failed with error code {0}", objOutParams.ReturnValue)
end if
End Function
'-----------------------------------------------------------------
' Create the console log files.
'-----------------------------------------------------------------
Sub WriteLog(line)
dim fileStream
set fileStream = fileSystem.OpenTextFile(".\BindExternalEthernetPort.log", 8, true)
WScript.Echo line
fileStream.WriteLine line
fileStream.Close
End Sub
'------------------------------------------------------------------------------
' The string formatting functions to avoid string concatenation.
'------------------------------------------------------------------------------
Function Format1(myString, arg0)
Format1 = Replace(myString, "{0}", arg0)
End Function
Requirements
| Minimum supported client |
None supported |
| Minimum supported server |
Windows Server 2008 |
| End of client support |
None supported |
| End of server support |
Windows Server 2012 |
| Namespace |
Root\Virtualization |
| MOF |
|