[This is preliminary documentation and subject to change.]
The msbdnOutputCreate function creates and initializes a single instance of a virtual interface.
HRESULT msbdnOutputCreate(
OUT MSBDN_OUTPUT_SUBSYSTEM *Subsystem,
IN DWORD ApiVersion
);
Returns zero if the function was successful. If the function fails, the return value is non-zero. If this function is unable to allocate memory for an instance of the virtual interface, this function should return E_OUTOFMEMORY.
After loading a virtual interface DLL, the MMR immediately calls the msbdnOutputCreate function. This function is only called once, and no other virtual interface functions are called until this function returns.
The msbdnOutputCreate function should create any synchronization objects that it requires and try to connect to and initialize the appropriate output system or device drivers it will use. If a virtual interface DLL stores values in the registry when the DLL starts, msbdnOutputCreate should call the RegQueryValueEx Win32 function for each configuration value and pass the open registry key contained in the Subsystem parameter, the name of the configuration value to retrieve, and a buffer to hold the configuration data. The msbdnOutputCreate function could also provide default data for each configuration value. The msbdnOutputCreate function should then store retrieved or provided configuration data in values defined by the virtual interface. When the MMR requires a dynamic value from the virtual interface's configuration, the MMR calls msbdnOutputGetValue to retrieve such a value.
If msbdnOutputCreate cannot initialize an instance of the virtual interface, it should return a failure condition. The msbdnOutputCreate function should only return a failure condition if there is some condition that prevents the virtual interface from ever running correctly. For example, the virtual interface should not return an error condition if some configuration parameter prevents the hardware from functioning because the virtual interface can only change configuration parameters of the hardware if this function succeeds.
The msbdnOutputCreate function allows the MMR to specify the version of the virtual interface interface that a particular virtual interface is required to support. The function also allows the MMR to retrieve details about the virtual interface's implementation.
In order for the MMR to support future implementations of the virtual interface interface that might have functionality different from that current, a negotiation should take place in msbdnOutputCreate. The MMR and the particular virtual interface DLL indicate to each other the highest interface version that they can support. Each confirms that the other's highest version is acceptable, if it is.
To do so, the virtual interface DLL examines the version requested by the MMR. If this version is equal to or higher than the lowest version supported by the DLL, the call succeeds. On a successful call, the DLL returns the highest version it supports in the Version member of MSBDN_OUTPUT_SUBSYSTEM. In the structure's Version member, the virtual interface DLL returns either the highest version it supports or the version number that the MMR is requesting, whichever is lower.
After msbdnOutputCreate returns, the virtual interface DLL works under the assumption that the MMR uses the interface version returned in Version. If the MMR cannot work with this version, the MMR does not call any other virtual interface functions.
This negotiation allows both a virtual interface DLL and the MMR to support a range of function versions. The MMR can successfully use a virtual interface DLL if there is any overlap in the version ranges.
msbdnOutputDestroy, msbdnOutputGetValue, MSBDN_OUTPUT_SUBSYSTEM