3.1.4.2 Application Requests Opening a Shared Virtual Disk

  • Article

The application provides the following:

  • The name of the server to connect to.

  • The name of the share to connect to.

  • InitiatorId to uniquely identify the initiator (optional).

  • User credentials, an opaque implementation-specific entity that identifies the credentials to be used when authenticating to the remote server.

  • The shared virtual disk file name to open.

  • The flags for open command (optional).

  • The Initiator host name.

  • A Boolean that, if set, requires the shared virtual disk file to be opened as virtual SCSI disk.

Upon successful completion, the client MUST return a handle to the application.

If ClientServiceVersion is RSVD Protocol version 1, the client MUST construct an SVHDX_OPEN_DEVICE_CONTEXT as specified in section 2.2.4.12, or if ClientServiceVersion is RSVD Protocol version 2, the client MUST construct an SVHDX_OPEN_DEVICE_CONTEXT_V2 as specified in section 2.2.4.32 and MUST be initialized as follows:

  • The InitiatorId field is set to the application-provided InitiatorId, if any. Otherwise, InitiatorId is set to zero.

  • The HasInitiatorId field is set to TRUE if the application provides initiator Id; otherwise set to FALSE.

  • The Flags field is set to application-provided flags.

  • If the application requires the shared virtual disk file to be opened as a virtual SCSI disk device, the client MUST set OriginatorFlags to SVHDX_ORIGINATOR_PVHDPARSER. Otherwise, it MUST be set to SVHDX_ORIGINATOR_VHDMP.

  • The OpenRequestId is set to RequestIdentifier.

  • The InitiatorHostNameLength is set to InitiatorHostName length, in bytes.

  • The InitiatorHostName is set to the application-provided initiator host name. If InitiatorHostNameLength is less than 126 bytes, the remaining bytes in the buffer MUST be set to zero.

The client MUST append ":SharedVirtualDisk" at the end of the file name.

The client MUST establish a connection to the server by calling the interface specified in [MS-SMB2] section 3.2.4.2 and providing the following input parameters:

  • The application-provided server name.

  • The application-provided share name.

  • The application-provided user credentials.

If the connection is successfully established, the client MUST open the shared virtual disk file by calling the interface specified in [MS-SMB2] section 3.2.4.3 and provide the following input parameters:

  • File name

  • The SVHDX_OPEN_DEVICE_CONTEXT Create context if ClientServiceVersion is RSVD Protocol version 1 or SVHDX_OPEN_DEVICE_CONTEXT_V2 Create context if ClientServiceVersion is RSVD Protocol version 2

  • CreateOptions as specified in [MS-SMB2] section 2.2.13 with the FILE_NO_INTERMEDIATE_BUFFERING bit set

If there are any errors from the preceding call, return the error to the caller.