IWSMan::CreateSession method (wsmandisp.h)

Creates a Session object that can then be used for subsequent network operations.

Syntax

HRESULT CreateSession(
  [in]  BSTR      connection,
  [in]  long      flags,
  [in]  IDispatch *connectionOptions,
  [out] IDispatch **session
);

Parameters

[in] connection

The protocol and service to connect to, including either IPv4 or IPv6. The format of the connection information is as follows: <Transport><Address><Suffix>. For examples, see Remarks. If no connection information is provided, the local computer is used.

[in] flags

The session flags that specify the authentication method, such as Negotiate authentication or Digest authentication, for connecting to a remote computer. These flags also specify other session connection information, such as encoding or encryption. This parameter must contain one or more of the flags in __WSManSessionFlags for a remote connection. For more information, see Session Constants. No flag settings are required for a connection to the WinRM service on the local computer.

If no authentication flags are specified, Kerberos is used unless one of the following conditions is true, in which case Negotiate is used:

  • explicit credentials are supplied and the destination host is trusted
  • the destination host is "localhost", "127.0.0.1" or "[::1]"
  • the client computer is in a workgroup and the destination host is trusted
For more information, see Authentication for Remote Connections and the connectionOptions parameter.

[in] connectionOptions

A pointer to an IWSManConnectionOptions object that contains a user name and password. The default is NULL.

[out] session

A pointer to a new IWSManSession object.

Return value

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

The following list contains examples of formats used to specify connection information in the connection parameter (when creating an HTTPS session, the <Address> field must match the server computer certificate name, otherwise a failure occurs):

  • "https://service"

    Uses HTTPS to connect to the default web service location.

  • "https://service.corp.com/websvcs/wsman"

    Uses HTTPS to connect to the specific web service location.

  • "https://[E3D7:0000:0000:0000:51F4:9BC8:C0A8:6420]"

    Uses HTTPS and IPv6 with the default port.

  • "https://[E3D7:0000:0000:0000:51F4:9BC8:C0A8:6420]:9999/wsman"

    Uses HTTPS and IPv6 with the given port.

Requirements

   
Minimum supported client Windows Vista
Minimum supported server Windows Server 2008
Target Platform Windows
Header wsmandisp.h
Library WSManDisp.tlb
DLL WSMAuto.dll

See also

IWSMan

WSMan.CreateSession