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

Show: