API Remote Assistance

  • View
    141

  • Download
    2

Embed Size (px)

Text of API Remote Assistance

Offering Remote Assistance

Microsoft Corporation June 2003 Applies to: Microsoft Remote Assistance Microsoft Windows XP Microsoft Windows Server 2003 Summary: This whitepaper details the information necessary to build a customized solution based on the Offer Remote Assistance feature of Remote Assistance. The objects and sample code provided below may be used to integrate the Offer Remote Assistance solution into the workflow of a help desk organization. (23 printed pages) Contents Unsolicited Remote Assistance objects Remote Assistance Ticket

Unsolicited Remote Assistance objectsSAFRemoteDesktopConnection ObjectPropertiesy

None

Methodsy

ConnectRemoteDesktop Copy[jscript] Obj.ConnectRemoteDesktop(remoteMachineName)

Arguments Input

Remote Machine Name-This can be an IP Address or DNS Server Name of the remote machine. Returns SAFRemoteConnectionData Object. Description After establishing a connection with the remote computer, this method returns all session information for every user logged on to the remote computer. This information is populated in the SAFRemoteConnectionData object that is returned by the method. This method does not include the disconnected Terminal Server sessions and the Session with ID 65536 that is used internally by Terminal Services. This method may only be called from script executed within Help Center. Offer Remote Assistance Sample JScript Requirements Client: Included in Microsoft Windows XP or Windows Server 2003 Library: Use HelpServiceInterfaces.tlb

SAFRemoteConnectionData Object:Propertiesy

None

Methodsy

Users Copy[jcsript] Obj.Users()

Arguments Input

None Returns PCHCollection object Description This method returns the collection of all the logged on users. All the user information is returned as a standard collection i.e. PCHCollection. The members of this collection are objects of type SAFUser. This method may only be called from script executed within Help Center. Offer Remote Assistance Sample JScript Requirements: Client: Included in Windows XP or Windows Server 2003 Library: Use HelpServiceInterfaces.tlby

Sessions Copy[jscript] Obj.Sessions(optional var UserName, optional var DomainName)

Arguments Input UserNameUser on remote machine DomainNameDomain of user on remote machine Returns PCHCollection object Description This method returns a PCHCollection containing session information for all logged on users of a remote machine if no input parameters are specified. The

members of this collection are objects of type SAFSession. If input parameters are specified then only the session information for the specified user is returned. This method may only be called from script executed within Help Center. Offer Remote Assistance Sample JScript Requirements Client: Included in Windows XP or Windows Server 2003 Library: Use HelpServiceInterfaces.tlby

ConnectionParms Copy[jscript] Obj.ConnectionParms(var RemoteMachineName, var RemoteUserName, var RemoteDomainName, var RemoteSessionID, var bstrUserHelpBlob)

Arguments Input RemoteMachineName: The name of the remote machine that you are creating the Remote Assistance ticket for. RemoteUserName: The name of the user that you are creating a Remote Assistance ticket for on the remote machine. RemoteDomainName: The domain name of the user that you are creating a Remote Assistance ticket for on the remote machine. RemoteSessionID: The session ID on the remote machine that you are creating a Remote Assistance ticket for. BstrUserHelpBlob: This is reserved and should always be a null string. Returns Connection Parameter StringUsed by the expert to connect to the remote (novice) computer. Description

This method gets the connection parameters for a specified User Name, Domain Name, Session ID. The connection parameter string that is returned is a Remote Assistance ticket based on the input parameters. This method may only be called from script executed within Help Center. Offer Remote Assistance Sample JScript Requirements Client: Included in Windows XP or Windows Server 2003 Library: Use HelpServiceInterfaces.tlby

ModemConnected Copy[jscript] Obj.ModemConnected(ServerName)

Arguments Input ServerNamestring containing the name of the remote computer that you want to determine the connection type of (modem or broadband/other) Returns Boolean value determining connection type. True = Modem False = Broadband/other Description This method is used to determine the connection type of the remote computer. This can then be used to set the color depth setting (see Remote Assistance Ticket) to optimize for bandwidth. This method may only be called from script executed within Help Center. Not supported on Windows XP or Windows XP SP1 Offer Remote Assistance Sample JScript

Requirements Client: Included in Windows Server 2003 Library: Use HelpServiceInterfaces.tlb

SAFUser ObjectPropertiesy

DomainName Copy[jscript] Obj.DomainName

Arguments Input None Output Domain name of the user logged on to the remote computer. Description DomainName contains the domain name of user logged on to the remote Computer. This object is only accessible from script in Help Center Offer Remote Assistance Sample JScript Requirements Client: Included in Windows XP or Windows Server 2003 Library: Use HelpServiceInterfaces.tlby

UserName Copy

[jscript] Obj.UserName

Arguments: Input: None Return User name of the user logged on to the remote computer. Description User Name contains the user name of the user logged on to the remote computer. This method may only be called from script executed within Help Center. Offer Remote Assistance Sample JScript Requirements Client: Included in Windows XP or Windows Server 2003 Library: Use HelpServiceInterfaces.tlb

SAFSession ObjectDescription The SAF Session object contains the Session State, Session ID, UserName and Domain Name information for all the logged on users. Propertiesy

SessionID Copy[jscript] Obj.SessionID [c] [propget, id(DISPID_SAF_SESS__SESSIONID [out, retval] DWORD *pVal ); [c]

)] HRESULT SessionID

(

[propput, id(DISPID_SAF_SESS__SESSIONID [in ] DWORD pVal );

)] HRESULT SessionID

(

Description Contains the SessionID of the session on the remote computer. Offer Remote Assistance Sample C Offer Remote Assistance Sample JScript Requirements Client: Included in Windows XP or Windows Server 2003 Library: Use HelpServiceInterfaces.tlby

Session State: Copy[jscript] Obj.SessionState [c] [propget, id(DISPID_SAF_SESS__SESSIONSTATE)] HRESULT SessionState( [out, retval] SessionStateEnum *pVal ); [c] [propput, id(DISPID_SAF_SESS__SESSIONSTATE)] HRESULT SessionState( [in ] SessionStateEnum pVal );UserName:

Description Contains the SessionState of the session on the remote Computer. This can be one of the following: PchActive pchConnected = 0, // User logged on to WinStation = 1, // WinStation connected to client

pchConnectQuery = 2, pchShadow pchDisconnected pchIdle = 3, = 4, = 5,

// In the process of connecting to client // Shadowing another WinStation // WinStation logged on without client

// Waiting for client to connect

pchListen pchReset pchDown pchInit pchStateInvalid

= 6, = 7,

// WinStation is listening for connection // WinStation is being reset

= 8, // WinStation is down due to error = 9, // WinStation in initialization =10 //Winstation state is invalid

Offer Remote Assistance Sample C Offer Remote Assistance Sample JScript Requirements Client: Included in Windows XP or Windows Server 2003 Library: Use HelpServiceInterfaces.tlby

DomainName Copy[jscript] Obj.DomainName [c] [propget, id(DISPID_SAF_SESS__DOMAINNAME )] HRESULT DomainName [out, retval] BSTR *pVal ); [c] [propput, id(DISPID_SAF_SESS__DOMAINNAME )] HRESULT DomainName [in ] BSTR pVal );

( (

Description Contains the DomainName of the owner of the session. Offer Remote Assistance Sample C Offer Remote Assistance Sample JScript Requirements Client: Included in Windows XP or Windows Server 2003 Library: Use HelpServiceInterfaces.tlb

y

UserName Copy[jscript] Obj.UserName [c] [propget, id(DISPID_SAF_SESS__USERNAME )] HRESULT UserName [out, retval] BSTR *pVal ); [c] [propput, id(DISPID_SAF_SESS__USERNAME )] HRESULT UserName [in ] BSTR pVal );

( (

Description Contains the UserName of the owner of the session. Offer Remote Assistance Sample C Offer Remote Assistance Sample JScript Requirements Client: Included in Windows XP or Windows Server 2003 Library: Use HelpServiceInterfaces.tlb

PCHServicey

RemoteConnectionParms CopyHRESULT RemoteConnectionParms([in] BSTR bstrUserName, [in ] BSTR bstrDomainName [in ], [in ] long lSessionID , [in ] BSTR bstrUserHelpBlob , [out, retval] BSTR *bstrConnectionString );

Parameters Input UserNameUser name of the session on the novices machine that you wish to get connection parameters for. DomainNameDomain name of the session on the novices machine that you wish to get connection parameters for.

SessionIDSession ID of the session on the novices machine that you wish to get connection parameters for. bstrUserHelpBlobInternal to Remote Assistance. It is recommended that a null value is always passed in here. Output Connection Parameter StringUsed by the expert to connect to the remote (novice) computer. Returns Standard HRESULT that indicates a success or failure. Description This method gets the connection parameters for a specified User Name, Domain Name, Session ID. This is the interface used on the expert side. Remarks When Remote Assistance is disabled in System Properties and Remote Assistance group policies are not configured or disabled on the server (novice machine), calling RemoteConnectionParms