2.2.6 WDS_OP_IMG_ENUMERATE
This opcode is used to enumerate all OS images available on the server and accessible to the client.
The request packet MUST include the following:
VERSION (WDSCPL_VAR_ULONG): MUST be set to 1.
The request packet MAY<14> include the following:
CC (WDSCPL_VAR_ULONG): This variable is used to specify the capabilities of the client. The value for this parameter is a bitwise OR of the following:
|
Flag |
Description |
|---|---|
|
CLIENT_CAP_SUPPORT_V2 0x00000001 |
MUST be set if the client supports the version 2.0 format that is used to return information for each OS image. |
|
CLIENT_CAP_SUPPORT_VHDX 0x00000002 |
MUST be set if the client is capable of deploying OS images in the VHDX format.<15> |
If the client used WDSDCMGR_OP_QUERY_METADATA to get deployment agent metadata from the server as specified in section 2.2.9, the client SHOULD<16> include this in the request packet in the following variables:
IMDC (WDSCPL_VAR_ULONG): MUST specify the same value specified by the Metadata.Count variable in the server's response to WDSDCMGR_OP_QUERY_METADATA.
The md_index in the following variable is a placeholder and is replaced by a value of zero in order to generate the variable name for the first variable, and incremented for subsequent variables up to (IMDC - 1). In this manner the request packet MUST include IMDC instances of the following variable:
IMD[md_index] (WDSCPL_VAR_WSTRING): MUST specify the same values specified by the Metadata.Entry[index] variables in the same order in the server's response to WDSDCMGR_OP_QUERY_METADATA.
The reply packet from the server MUST include the following variables:
VERSION (WDSCPL_VAR_ULONG): MUST be set to 1.
The following variables MAY be present in the reply packet:
OPTIONS (WDSCPL_VAR_ULONG): The value for this variable is a bitwise OR of the following:
|
Flag |
Description |
|---|---|
|
WdsCliFlagEnumFilterVersion 0x00000001 |
MAY be set to instruct the client to display only the OS images that exactly match the version of the OS currently running on the client machine and being used for deployment. |
|
WdsCliFlagEnumFilterFirmware 0x00000002 |
MAY be set to instruct the client to display only the OS images for selection that match the firmware type of the client machine. |
SC (WDSCPL_VAR_ULONG): If the request packet specifies the CC variable, and the server supports at least one of the capabilities specified by the client, then the reply packet MUST include this variable. The value for this variable is a bitwise OR of the following:
|
Flag |
Description |
|---|---|
|
SERVER_CAP_SUPPORT_V2 0x00000001 |
MUST be set if the client specifies the CC variable with the CLIENT_CAP_SUPPORT_V2 flag set, and the server supports the version 2.0 format for returning the list of OS images. |
|
SERVER_CAP_SUPPORT_VHDX 0x00000002 |
MUST be set if the client specifies the CC variable with the CLIENT_CAP_SUPPORT_VHDX flag set and the CLIENT_CAP_SUPPORT_V2 flag set, and the server supports the version 2.0 format for returning the list of OS images, and the server supports deploying OS images in the VHDX format.<17> |
If the reply packet does not have an SC variable, or the value for the variable does not have the SERVER_CAP_SUPPORT_V2 flag set, then information for each OS image available to the client is available as follows:<18>
XML_index (WDSCPL_VAR_WSTRING): MUST be set to the OS image metadata.
PATH_index (WDSCPL_VAR_WSTRING): MUST be set to the relative path of the OS image container file on WDS server.<19>
GROUP_index (WDSCPL_VAR_WSTRING): MUST be set to the image group to which the OS image belongs.
INDEX_index (WDSCPL_VAR_ULONG): MUST be set to the unique numeric index of the OS image in the OS image container.
NAMESPACE_index (WDSCPL_VAR_WSTRING): MAY<20> be present in a reply packet; MUST be set to the multicast namespace that MAY be available and can provide the files for the OS image container using multicast transmission. If multicast transmission is not available, this variable MUST be set to an empty string.
RESOURCEFILEPATH_index (WDSCPL_VAR_WSTRING): MAY be present in a reply packet.<21> For an OS image container that uses two files to package OS images, this variable is set to the relative path of the second file for the OS image container.<22>
If the OS image container only has one file, this variable is set to the same value as the PATH_index variable.
NAMESPACE_SIZE_index (WDSCPL_VAR_ULONG64): MAY<23> be present; MUST be set to the estimated number of bytes that the client has to download using multicast transmission in order to fully download the OS image container onto the client machine.
To retrieve information for all OS images from the reply packet, the client MUST substitute an index with a value of 1 and retrieve all variables for the first OS image. The client MUST increment the index for each iteration and continue to retrieve information for subsequent OS images until the variables generated by using the next index value are not found in the reply packet.
If the reply packet specifies the SC variable and it has SERVER_CAP_SUPPORT_V2 flag set<24>, then information for each OS image available to the client is available as follows:
IL.Type[index] (WDSCPL_VAR_ULONG): MUST be set to the type of OS image as specified in the following table:
|
Image type |
Description |
|---|---|
|
DEP_IMAGE_VHD 0x00000001 |
MUST be set for OS images of type VHD Image. |
|
DEP_IMAGE_WIM 0x00000002 |
MUST be set for OS images of type WIM Image. |
|
DEP_IMAGE_VHDX 0x00000003 |
MUST be set for OS images of type VHDX image. If the server does not specify the SC variable with the SERVER_CAP_SUPPORT_VHDX flag, the server MUST NOT specify any instances of DEP_IMAGE_VHDX in the reply packet.<25> |
IL.Xml[index] (WDSCPL_VAR_WSTRING): MUST be set to the OS image metadata.
IL.Path[index] (WDSCPL_VAR_WSTRING): MUST set to the relative path of the OS image container file on WDS server.<26>
IL.ResPath[index] (WDSCPL_VAR_WSTRING): For OS image containers that have more than one file, this parameter specifies the second file for the OS image container.<27>
IL.Group[index] (WDSCPL_VAR_WSTRING): MUST be set to the image group the OS image belongs to.
IL.Index[index] (WDSCPL_VAR_ULONG): MUST be set to the unique numeric index of the OS image in the OS image container.
IL.NS[index] (WDSCPL_VAR_WSTRING): MUST be set to the multicast namespace that MAY be available and can provide the files for the OS image container using multicast transmission.
IL.NSCS[index] (WDSCPL_VAR_ULONG64): MUST be set to the estimated number of bytes that the client has to download using multicast transmission in order to fully download the OS image container on the client machine.
IL.ExFlags[index] (WDSCPL_VAR_ULONG): The value for this variable is a bitwise OR the flags as specified in the following table:
|
Flag |
Description |
|---|---|
|
EX_FLAG_SPARSE_FILE 0x00000001 |
This flag indicates that the deployment agent MUST NOT use the sparse file feature of the file system when downloading the OS image container files from the WDS server using multicast transmission. |
IL.DepFiles[index].Cnt (WDSCPL_VAR_ULONG): MUST be set to the total number of files for an OS image container.
IL.DepFiles[index].VL[file_index] (WDSCPL_VAR_WSTRING): MUST be set to the relative path of the files on WDS server.<28>
To retrieve all dependent files for an OS image container, the client must substitute file_index with a value of zero and retrieve the value for the resulting variable. The client MUST continue to increment the file_index up to (DepFiles[index].Cnt - 1) to retrieve all files.
IL.MdGuid[index] (WDSCPL_VAR_BLOB): MAY<29> be specified by the server to indicate a unique identifier for the OS image. If this variable is specified, it MUST be a 16-byte value storing a GUID that was assigned by the server to the OS image and that uniquely identifies the OS image among other OS images in the image store.