xrdp/libipm/eicp.h

303 lines
9.2 KiB
C

/**
* xrdp: A Remote Desktop Protocol server.
*
* Copyright (C) Jay Sorg 2004-2022, all xrdp contributors
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
*
* @file libipm/eicp.h
* @brief EICP declarations
* @author Matt Burt
*
* Functions in this file use the following naming conventions:-
*
* E_EICP_{msg}_REQUEST is sent by eicp_send_{msg}_request()
* E_EICP_{msg}_REQUEST is parsed by eicp_get_{msg}_request()
* E_EICP_{msg}_RESPONSE is sent by eicp_send_{msg}_response()
* E_EICP_{msg}_RESPONSE is parsed by eicp_get_{msg}_response()
*/
#ifndef EICP_H
#define EICP_H
#include "arch.h"
#include "scp_application_types.h"
struct trans;
struct guid;
/* Message codes */
enum eicp_msg_code
{
E_EICP_SYS_LOGIN_REQUEST,
E_EICP_SYS_LOGIN_RESPONSE,
E_EICP_LOGOUT_REQUEST,
// No E_EICP_LOGOUT_RESPONSE
E_EICP_CREATE_SESSION_REQUEST
// No E_EICP_CREATE_SESSION_RESPONSE
};
/* Common facilities */
/**
* Convert a message code to a string for output
* @param n Message code
* @param buff to contain string
* @param buff_size length of buff
* @return buff is returned for convenience.
*/
const char *
eicp_msgno_to_str(enum eicp_msg_code n, char *buff, unsigned int buff_size);
/* Connection management facilities */
/**
* Converts a standard trans connected to an EICP endpoint to an EICP transport
*
* @param trans connected endpoint
* @return != 0 for error
*/
int
eicp_init_trans(struct trans *trans);
/**
* Creates an EICP transport from a file descriptor
*
* @param fd file descriptor
* @param trans_type TRANS_TYPE_SERVER or TRANS_TYPE_CLIENT
* @param term_func Function to poll during connection for program
* termination, or NULL for none.
* @return SCP transport, or NULL
*/
struct trans *
eicp_init_trans_from_fd(int fd, int trans_type, int (*term_func)(void));
/**
* Checks an EICP transport to see if a complete message is
* available for parsing
*
* @param trans EICP transport
* @param[out] available != 0 if a complete message is available
* @return != 0 for error
*/
int
eicp_msg_in_check_available(struct trans *trans, int *available);
/**
* Waits on a single transport for an EICP message to be available for
* parsing
*
* @param trans libipm transport
* @return != 0 for error
*
* While the call is active, data-in callbacks for the transport are
* disabled.
*
* Only use this call if you have nothing to do until a message
* arrives on the transport. If you have other transports to service, use
* eicp_msg_in_check_available()
*/
int
eicp_msg_in_wait_available(struct trans *trans);
/**
* Gets the EICP message number of an incoming message
*
* @param trans EICP transport
* @return message in the buffer
*
* The results of calling this routine before eicp_msg_in_check_available()
* states a message is available are undefined.
*/
enum eicp_msg_code
eicp_msg_in_get_msgno(const struct trans *trans);
/**
* Resets an EICP message buffer ready to receive the next message
*
* @param trans libipm transport
*/
void
eicp_msg_in_reset(struct trans *trans);
/* -------------------- Connect messages-------------------- */
/**
* Send an E_EICP_SYS_LOGIN_REQUEST
*
* @param trans EICP transport
* @param username Username
* @param password Password
* @param ip_addr IP address for the client (or "" if not known)
* @param scp_fd SCP file descriptor from sesman client
* @return != 0 for error
*
* sesexec replies (eventually) with E_EICP_SYS_LOGIN_RESPONSE
*
* Once this message has been sent, sesman can close its own SCP transport
* down, as sesexec is responsible for client communication. When sesexec
* responds, sesman can recreate the SCP transport if necessary.
*
* While E_EICP_SYS_LOGIN_REQUEST is being processed, sesman must assume
* sesexec will be unresponsive to other EICP messages (although a
* SIGTERM should be effective).
*/
int
eicp_send_sys_login_request(struct trans *trans,
const char *username,
const char *password,
const char *ip_addr,
int scp_fd);
/**
* Parse an incoming E_EICP_SYS_LOGIN_REQUEST message (sesexec)
*
* @param trans EICP transport
* @param[out] username Username
* @param[out] password Password
* @param[out] ip_addr IP address for the client (or "" if not known)
* @param [out] scp_fd SCP file descriptor from sesman client
* @return != 0 for error
*/
int
eicp_get_sys_login_request(struct trans *trans,
const char **username,
const char **password,
const char **ip_addr,
int *scp_fd);
/**
* Send an E_EICP_SYS_LOGIN_RESPONSE (sesexec)
*
* @param trans EICP transport
* @param is_logged_in true if the SCP client is logged in
* @param uid UID of connected user
* @param scp_fd File descriptor of sesman client
* @return != 0 for error
*
* The uid and scp_fd are ignored unless is_logged_in is true.
*
* If is_logged_in is false, it is assumed that sesexec has properly
* closed the connection to the SCP client.
*/
int
eicp_send_sys_login_response(struct trans *trans,
int is_logged_in,
uid_t uid,
int scp_fd);
/**
* Parses an incoming E_EICP_SYS_LOGIN_RESPONSE (sesexec)
*
* @param trans EICP transport
* @param[out] is_logged_in true if the SCP client is logged in
* @param[out] uid UID of connected user
* @param[out] scp_fd File descriptor of sesman client
* @return != 0 for error
*
* The uid and client_fd are returned as (uid_t)-1 and -1 respectively
* unless is_logged_in is true
*/
int
eicp_get_sys_login_response(struct trans *trans,
int *is_logged_in,
uid_t *uid,
int *scp_fd);
/**
* Send an E_EICP_LOGOUT_REQUEST (sesexec)
*
* @param trans EICP transport
* @return != 0 for error
*
* The sesexec process will exit normally
*/
int
eicp_send_logout_request(struct trans *trans);
/* -------------------- Session messages-------------------- */
/**
* Send an E_EICP_CREATE_SESSION_REQUEST (sesman)
*
* @param trans EICP transport
* @param scp_fd SCP file descriptor from sesman client
* @param display X display number to use
* @param type Session type
* @param width Initial session width
* @param height Initial session height
* @param bpp Session bits-per-pixel (ignored for Xorg sessions)
* @param shell User program to run. May be ""
* @param directory Directory to run the program in. May be ""
* @return != 0 for error
*
* The UID for the session comes from one of two places:-
* - The UID for a sys login request is used if one has successfully
* been executed.
* - If no sys login request is used, the UID is taken from the scp_fd
*
* Following a successful request, the session creation can be
* considered to be underway. The result of this operation is
* conveyed back to the caller as an ERCP event. The caller must use
* ercp_trans_from_eicp_trans() on 'trans' to convert the transport to
* an ERCP transport to receive this (and other) session run-time events.
*/
int
eicp_send_create_session_request(struct trans *trans,
int scp_fd,
unsigned int display,
enum scp_session_type type,
unsigned short width,
unsigned short height,
unsigned char bpp,
const char *shell,
const char *directory);
/**
* Parse an incoming E_EICP_CREATE_SESSION_REQUEST (sesexec)
*
* @param trans EICP transport
* @param[out] scp_fd SCP file descriptor from sesman client
* @param[out] display X display number to use
* @param[out] type Session type
* @param[out] width Initial session width
* @param[out] height Initial session height
* @param[out] bpp Session bits-per-pixel (ignored for Xorg sessions)
* @param[out] shell User program to run. May be ""
* @param[out] directory Directory to run the program in. May be ""
* @return != 0 for error
*
* Returned string pointers are valid until scp_msg_in_reset() is
* called for the transport
*/
int
eicp_get_create_session_request(struct trans *trans,
int *scp_fd,
unsigned int *display,
enum scp_session_type *type,
unsigned short *width,
unsigned short *height,
unsigned char *bpp,
const char **shell,
const char **directory);
#endif /* EICP_H */