2.2.3.17 Host Method Identifier
This data type represents a method to be executed on a host.
This data type is an enum (as specified in section 2.2.5.2.7) based on the default underlying type (signed int, as specified in section 2.2.5.1.11) that defines the named constants listed in the following tables.
The following table lists the possible values for method identifiers when a server invokes a host method on the client. What the host methods SHOULD or MUST do is also defined in the table.
The client MUST hand over requests for execution of a host method to a higher-layer host. The host will either perform the action described in the Method Details column of the following table, or indicate that there was an error executing the host method (if the method is not supported or not implemented, for instance).
If the Return Value column indicates that the method returns a return value, the client MUST send a RUNSPACEPOOL_HOST_RESPONSE message (see section 2.2.2.16) or a PIPELINE_HOST_RESPONSE message (see section 2.2.2.28). If the higher-layer host reported an error after executing the host method, then the response message MUST include the "me" property. If the higher-layer host returned a return value after executing the host method, then the response message MUST include the "mr" property and the client MUST make sure that the data type of the "mr" property is the same as the type of return value described in the following Return Value column.
If the Return Value column indicates that the method does not return a value, the client MUST NOT send a RUNSPACEPOOL_HOST_RESPONSE message (see section 2.2.2.16) or a PIPELINE_HOST_RESPONSE message (see section 2.2.2.28).
Host Read Only Properties
|
Name of method/property |
Method identifier |
Return value |
Method details |
|---|---|---|---|
|
GetName |
1 |
String (section 2.2.5.1.1) |
SHOULD return a string identifying the hosting application in a user friendly way. |
|
GetVersion |
2 |
Version number (section 2.2.5.1.21) |
SHOULD return the version number of the hosting application. |
|
GetInstanceId |
3 |
GUID (section 2.2.5.1.18) |
SHOULD return a GUID that uniquely identifies the hosting application. |
|
GetCurrentCulture |
4 |
CultureInfo (section 2.2.6.1.2) |
SHOULD return the host's culture. |
|
GetCurrentUICulture |
5 |
CultureInfo (section 2.2.6.1.2) |
MUST return the host's UI culture. |
Host Methods
|
Name of method/property |
Method identifier |
Return value |
Method details |
|---|---|---|---|
|
SetShouldExit |
6 |
None |
SHOULD shut down the hosting application and close the current runspace. |
|
EnterNestedPrompt |
7 |
None |
SHOULD interrupt the current pipeline and start a nested pipeline. |
|
ExitNestedPrompt |
8 |
None |
SHOULD stop the nested pipeline and resume the current pipeline. |
|
NotifyBeginApplication |
9 |
None |
Called by an application to indicate that it is executing a command line application. |
|
NotifyEndApplication |
10 |
None |
Called by an application to indicate that it has finished executing a command line application. |
Host UI Methods
|
Name of method/property |
Method identifier |
Return value |
Method details |
|---|---|---|---|
|
ReadLine |
11 |
String (section 2.2.5.1.1) |
SHOULD read a line of characters from a user. |
|
ReadLineAsSecureString |
12 |
Secure String (section 2.2.5.1.24) |
SHOULD read a line of characters from a user, with the user input not echoed. |
|
Write1 |
13 |
None. |
SHOULD write specified characters on the hosting application. |
|
Write2 |
14 |
None. |
SHOULD write the specified characters with the specified foreground and background color on the hosting application. |
|
WriteLine1 |
15 |
None. |
SHOULD write a carriage return on the hosting application. |
|
WriteLine2 |
16 |
None. |
SHOULD write the specified line on the hosting application. |
|
WriteLine3 |
17 |
None. |
SHOULD write the specified line with the specified foreground and background color on the hosting application. |
|
WriteErrorLine |
18 |
None. |
SHOULD write a line to the error display of the hosting application. |
|
WriteDebugLine |
19 |
None. |
SHOULD write a line to the debug display of the hosting application. |
|
WriteProgress |
20 |
None. |
SHOULD display a progress record on the hosting application. |
|
WriteVerboseLine |
21 |
None. |
SHOULD write a line on the verbose display of the hosting application. |
|
WriteWarningLine |
22 |
None. |
SHOULD write a line on the warning display of the hosting application. |
|
Prompt |
23 |
Dictionary (section 2.2.6.1.6) with String (section 2.2.5.1.1) keys representing the name of a field prompted for and values of arbitrary type. |
SHOULD prompt the user with a set of choices. |
|
PromptForCredential1 |
24 |
PSCredential (section 2.2.3.25) |
SHOULD prompt the user for entering credentials with the specified caption, message, user name and target name. |
|
PromptForCredential2 |
25 |
PSCredential (section 2.2.3.25) |
SHOULD prompt the user for entering credentials with the specified caption, message, username, target name, allowed credential types and options. |
|
PromptForChoice |
26 |
Signed int (section 2.2.5.1.11 |
SHOULD display a list of choices to the user and MUST return the index of the selected option. |
Host RawUI Read/Write Properties
|
Name of method/property |
Method identifier |
Return value |
Method details |
|---|---|---|---|
|
GetForegroundColor |
27 |
Color (section 2.2.3.3) |
SHOULD return the foreground color of the hosting application. |
|
SetForegroundColor |
28 |
None. |
SHOULD set the foreground color of the hosting application. |
|
GetBackgroundColor |
29 |
Color (section 2.2.3.3) |
SHOULD return the background color of the hosting application. |
|
SetBackgroundColor |
30 |
None. |
SHOULD set the background color of the hosting application. |
|
GetCursorPosition |
31 |
Coordinates (section 2.2.3.1) |
SHOULD return the current cursor position in the hosting application. |
|
SetCursorPosition |
32 |
None. |
SHOULD set the current cursor position in the hosting application. |
|
GetWindowPosition |
33 |
Coordinates (section 2.2.3.1) |
SHOULD return the position of the view window relative to the screen buffer. |
|
SetWindowPosition |
34 |
None. |
SHOULD set the position of the view window relative to the screen buffer. |
|
GetCursorSize |
35 |
Signed int (section 2.2.5.1.11) |
SHOULD return the cursor size as a percentage. |
|
SetCursorSize |
36 |
None. |
SHOULD set the cursor size based on the percentage value specified. |
|
GetBufferSize |
37 |
Size (section 2.2.3.2) |
SHOULD return the current size of the screen buffer, measured in character cells. |
|
SetBufferSize |
38 |
None. |
SHOULD set the size of the screen buffer with the specified size in character cells. |
|
GetWindowSize |
39 |
Size (section 2.2.3.2) |
SHOULD return the current view window size. |
|
SetWindowSize |
40 |
None. |
SHOULD set the view window size based on the size specified. |
|
GetWindowTitle |
41 |
String (section 2.2.5.1.1) |
SHOULD return the title of the hosting application's window. |
|
SetWindowTitle |
42 |
None. |
SHOULD set the title of the hosting application's window. |
Host RawUI Read Only Properties
|
Name of method/property |
Method identifier |
Return value |
Method details |
|---|---|---|---|
|
GetMaxWindowSize |
43 |
Size (section 2.2.3.2) |
SHOULD return the maximum window size possible for the current buffer, current font, and current display hardware. |
|
GetMaxPhysicalWindowSize |
44 |
Size (section 2.2.3.2) |
SHOULD return the maximum window size possible for the current font and current display hardware, ignoring the current buffer size. |
|
GetKeyAvailable |
45 |
Boolean (section 2.2.5.1.3) |
SHOULD examine if a keystroke is waiting on the input, returning TRUE if so and FALSE otherwise. |
Host RawUI Methods
|
Name of method/property |
Method identifier |
Return value |
Method details |
|---|---|---|---|
|
ReadKey |
46 |
KeyInfo (section 2.2.3.26) |
SHOULD read a key stroke from the keyboard, blocking until a key is typed. |
|
FlushInputBuffer |
47 |
None. |
SHOULD reset the keyboard input buffer. |
|
SetBufferContents1 |
48 |
None. |
SHOULD copy the specified buffer cell array into the screen buffer at the specified coordinates (as specified in section 2.2.3.1). |
|
SetBufferContents2 |
49 |
None. |
SHOULD copy the specified buffer cell into all the cells within the specified rectangle. |
|
GetBufferContents |
50 |
Array (section 2.2.6.1.4) of BufferCell elements (section 2.2.3.28) |
SHOULD return the contents in a specified rectangular region of the hosting application's window and MUST return an array of buffer cells. |
|
ScrollBufferContents |
51 |
None. |
SHOULD scroll a region on the screen buffer. |
IHostSupportsInteractiveSession Methods
|
Name of method/property |
Method identifier |
Return value |
Method details |
|---|---|---|---|
|
PushRunspace |
52 |
None. |
SHOULD store the current working runspace in a stack and replace it with the new specified runspace. |
|
PopRunspace |
53 |
None. |
SHOULD retrieve the last stored runspace from the stack and make it the current active runspace. |
IHostSupportsInteractiveSession Read Only Properties
|
Name of method/property |
Method identifier |
Return value |
Method details |
|---|---|---|---|
|
GetIsRunspacePushed |
54 |
Boolean (section 2.2.5.1.3) |
SHOULD validate if there is a runspace currently pushed on a stack in the host, returning true if so and false otherwise. |
|
GetRunspace |
55 |
Any object (section 2.2.5) that the higher layer uses to represent the current runspace. The PowerShell Remoting Protocol MUST transparently pass the data received from the host implemented in the higher layer. The PowerShell Remoting Protocol MUST ignore this value. |
SHOULD return the currently active runspace. |
IHostSupportsMultipleChoiceSelect Methods
|
Name of method/property |
Method identifier |
Return value |
Method details |
|---|---|---|---|
|
PromptForChoiceMultipleSelection |
56 |
Collection (section 2.2.6.1.5) of signed ints (section 2.2.5.1.11) |
SHOULD display a list of choices to the user and return a list of options selected by the user. |
The Complex Object described in this section SHOULD have the following type names (section 2.2.5.2.3):
System.Management.Automation.Remoting.RemoteHostMethodId
System.Enum
System.ValueType
System.Object