3.1.4.14 Receive

  • Article

Web Services Management Protocol Extensions for Windows Vista MUST support the Receive operation, using the following Action URIs.

 http://schemas.microsoft.com/wbem/wsman/1/windows/shell/Receive http://schemas.microsoft.com/wbem/wsman/1/windows/shell/ReceiveResponse
 

The set of resource URIs on which Web Services Management Protocol Extensions for Windows Vista MUST support the Receive operation is defined in the following table, and where relevant, the Xml Schema Definition (XSD) type for the data that is passed as part of the request or response is referenced.

Resource URI

Input data type

Output data type

http://schemas.microsoft.com/wbem/wsman/1/windows/shell/cmd

rsp:Receive

rsp:ReceiveResponse

In the Text-based Command Shell scenario, the Receive message is used to collect output from a running command, whereas in the Custom Remote Shell scenario, it is used to collect output from the Shell itself. Also, note that in case of the Text-based Command Shell scenario, a final Signal message MUST also be issued for the command after all the stream data has been received; it is not sufficient to simply use Receive to receive all the data. The Receive message MUST adhere to the following general form, with the only difference between the two scenarios being the value of the Resource URI. The Receive message format is as follows.

 <s:Envelope ...>
   <s:Header ...>
     <wsman:ResourceURI>
         Resource URI
     </wsman:ResourceURI>
     <wsman:SelectorSet>
        <wsman:Selector Name="ShellID">
              ...shell GUID...
        </wsman:Selector>
     </wsman:SelectorSet>
       ...other WS-Addressing & WS-Management headers...
   </s:Header>
   <s:Body ...>
     <rsp:Receive ...>
         ...Value defined by the Receive data type...
     </rsp:Receive>
   </s:Body>
 </s:Envelope>
 

The value of Resource URI will be different for the Text-based Command Shell and the Custom Remote Shell.

In case of Text-based Command Shell, the value of Resource URI MUST be as follows. http://schemas.microsoft.com/wbem/wsman/1/windows/shell/cmd

An example of Resource URI for Custom Remote Shell scenario is as follows. http://schemas.microsoft.com/wbem/wsman/1/windows/shell/CustomShell

The Web Services Management Protocol Extensions for Windows Vista service SHOULD<119> ignore the WSMAN_CMDSHELL_OPTION_KEEPALIVE option if it is included in a Receive request.

Upon successful processing of a Receive request message, the Shell processor MUST return a ReceiveResponse message, which MUST adhere to the following general form. The ReceiveResponse message format is as follows.

 <s:Envelope ...>
   <s:Header ...>
     <wsman:SelectorSet>
        <wsman:Selector Name="ShellID">
              ...shell GUID...
        </wsman:Selector>
     </wsman:SelectorSet>
       ...other WS-Addressing & WS-Management headers...
   </s:Header>
   <s:Body ...>
     <rsp:ReceiveResponse ...>
         ...Value defined by the ReceiveResponse data type...
     </rsp: ReceiveResponse>
   </s:Body>
 </s:Envelope>
 

The following rules apply to the Receive operation:

  1. When the Shell was opened with wst:Create, the client and service established a contractual obligation regarding the output streams that would be in use. The client MUST be prepared to accept output from any of these streams. If additional output streams are available and were not part of the initial wst:Create handshake, the server-side processor MUST omit these streams in the response.

  2. The Receive message MAY execute concurrently or asynchronously with Send messages, but only one Receive message SHOULD be outstanding at any given time.<120>

  3. A client SHOULD immediately issue a Receive message when a command is launched, whether or not it will be sending input using Send messages. To prevent deadlock, livelock, or time-out situations, the server can return Receive messages with empty string content, but typically it will delay responding until output is available, providing that wsman:OperationTimeout rules are not violated. If no output is available before the wsman:OperationTimeout expires, the server MUST return a WSManFault with the Code attribute equal to "2150858793". When the client receives this fault, it SHOULD issue another Receive request. The client SHOULD continue to issue Receive messages as soon as the previous ReceiveResponse has been received.

  4. At least one Receive message MUST be issued to get a final ReceiveResponse, which indicates that a command has terminated.

    In the case of the Text-based Command Shell scenario, the server MAY reject processing new Command requests and reply with an error response until it has successfully returned a ReceiveResponse with a CommandState element, indicating that the command has terminated or succeeded.<121>

    When the client receives the final output from a command, it MUST subsequently send a Signal with a code of

     http://schemas.microsoft.com/wbem/wsman/1/windows/shell/signal/Terminate

    to signal to the command processor that it MAY discard all final state information for the most recently executed command.

  5. In the case of the Text-based Command Shell scenario, while a stream MAY end by using the rsp:Stream/@End attribute, the completion of a command and consequently its entire output is distinct and signaled using the rsp:CommandState element with the <State> element having the value rsp:CommandState/Done.<122>

    The server MAY provide notification that a command is blocked while waiting for input stream content by returning the rsp:CommandState element with the <Status> element set to rsp:CommandState/Pending. The command state and its output is sent back to the client in the Custom Remote Shell scenario as part of a BLOB of data transparent to the Remote Shell protocol.<123>