| |
| HCLIENT WINAPI 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 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 server to connect to; this may be
a fully-qualified domain name or an IP address.
- nRemotePort
- The port number the 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 server considers the client to
be equivalent to itself, and as long as the specified user exists
on the server, 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
from the server before failing the current operation.
- dwOptions
- An unsigned integer that 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 server.
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 7, Windows Vista or Windows
XP.
Server: Requires Windows Server 2008 or Windows Server
2003.
Header: Include cstools7.h.
Library: Use csrshav7.lib.
Unicode: Implemented as Unicode and ANSI versions.
See Also
RshAsyncExecute, RshAsyncLogin, RshDisconnect, RshInitialize, RshLogin, RshSearch, RshUninitialize
|
|