MgslOpenDiagnostics

ULONG MgslOpenDiagnostics( ULONG PortID,
                           PHANDLE phDevice,
                           PULONG pStatus );

PortID

phDevice

pStatus

ERROR_SUCCESS (0)

ERROR_DEVICE_IN_USE

ERROR_ACCESS_DENIED

This function opens a port for diagnostics. This function behaves like the MgslOpen call with the following exceptions:

Under Windows NT 4.0 only, if ANY port is currently open then the MgslOpenDiagnostics call fails with ERROR_DEVICE_IN_USE.

If the call to MgslOpenDiagnostics succeeds then all subsequent calls to MgslOpen for ANY port fails with ERROR_DEVICE_IN_USE until MgslClose is called.

If the function returns ERROR_SUCCESS, then pStatus contains the port status as defined by the DiagStatus_XXX constants. If DiagStatus_OK is returned, the port is functioning correctly and a device handle is returned in phDevice, otherwise an error occurred as indicated by pStatus and NULL is returned in phDevice.

If a device handle is returned, the handle can be used with the other API calls to implement a loopback test. The device handle must be closed with MgslClose.

This function is used by the HDLC Ports control panel application to implement the port diagnostics.

Under Windows NT, calling this function requires administrative privilege. Under Windows NT, calling this function stops and restarts the device driver so that any recent changes to the port configuration are detected by the device driver. This allows the application to change the port configuration before calling this function in order to test a new configuration. After calling MgslClose, the API stops the device driver to allow the application to restore the original configuration. Subsequent calls to MgslOpen will restart the device driver.

Under Windows 95/98/ME and Windows 2000, Windows XP and later, this call can be performed without the requirement for administrative privileges.

See also: Opening the Port, Closing the Port