|
|
| HCLIENT
RshExecute(
|
|
|
LPCTSTR
lpszRemoteHost, |
|
|
|
|
UINT
nRemotePort, |
|
|
|
|
UINT nTimeout, |
|
|
|
|
DWORD
dwOptions, |
|
|
|
|
LPCTSTR
lpszUserName, |
|
|
|
|
LPCTSTR
lpszPassword, |
|
|
|
|
LPCTSTR
lpszCommand |
|
|
| );
|
The RshExecute function is used to establish a connection
with the remote server and execute the specified command. Whenever
a network event occurs, such as a successful connection, a message
is posted to the window specified by the hEventWnd
parameter. The message that is sent is specified by the
uEventMsg parameter.
Parameters
- lpszRemoteHost
- A pointer to the name of the remote host to connect to; this
may be a fully-qualified domain name, or an IP address.
- nRemotePort
- The port number the remote server is listening on. One of the
following values should be used:
| Constant |
| Description |
| RSH_PORT_REXEC |
A connection is established with
the server using port 512, the rexec service. This service requires
that the client provide a username and password to execute the
specified command. |
|
RSH_PORT_RSHELL |
A connection is established with
the server using port 514, the rshell service. This service uses
host equivalence to authenticate the user. With host equivalence,
the remote server considers the client to be equivalent to itself,
and as long as the specified user exists on the remote host, the
client is permitted to execute commands on behalf of the user
without requiring a password. Host equivalence is configured by the
server administrator. |
- nTimeout
- The number of seconds that the client will wait for a response
before failing the operation; a value of zero indicates that the
client should wait an indefinite period of time.
- dwOptions
- A bitmask which specifies one or more options. This parameter
is constructed by using a bitwise operator with any of the
following values:
| Constant |
| Description |
|
RSH_OPTION_RESERVEDPORT |
This option specifies that a
reserved port should be used to establish the connection. Reserved
ports are those port numbers which are less than 1024. This option
should be specified when connecting on the RSH_PORT_RSHELL
port. |
|
RSH_OPTION_FREETHREAD |
This option specifies that the
handle returned by this function may be used by any thread, and is
not limited to the thread which created it. The application is
responsible for ensuring that access to the handle is synchronized
across multiple threads. |
- lpszUserName
- A pointer to a null-terminated string which specifies the
username used to authenticate the client session.
- lpszPassword
- A pointer to a null-terminated string which specifies the
password used to authenticate the client session. This parameter is
only used when connecting to the RSH_PORT_REXEC port. If the
password is not required, this parameter may be NULL.
- lpszCommand
- A pointer to a null-terminated string which specifies the
command to execute on the remote host.
Return Value
If the function succeeds, the return value is a handle to a
client session. If the function fails, the return value is
INVALID_CLIENT. To get extended error information, call
RshGetLastError.
Remarks
The dwOptions argument can be used to specify the
threading model that is used by the library when a connection is
established. By default, the handle is initially attached to the
thread that created it. From that point on, until the it is
released, only the owner may call functions using that handle. The
ownership of the handle may be transferred from one thread to
another using the RshAttachThread function.
Specifying the RSH_OPTION_FREETHREAD option enables any thread
to call any function using the handle, regardless of which thread
created it. It is important to note that this option disables
certain internal safety checks which are performed by the library
and may result in unexpected behavior unless access to the handle
is synchronized. If one thread calls a function in the library, it
must ensure that no other thread will call another function at the
same time using the same handle.
Requirements
Client: Requires Windows Vista, Windows XP or Windows
2000 Professional.
Server: Requires Windows Server 2008, Windows Server 2003 or
Windows 2000 Server.
Header: Include cstools6.h.
Library: Use csrshav6.lib.
Unicode: Implemented as Unicode and ANSI versions.
See Also
RshAsyncExecute, RshAsyncLogin, RshDisconnect, RshInitialize, RshLogin, RshSearch, RshUninitialize
|
|