xrdp/libipm/scp.h

416 lines
12 KiB
C
Raw Normal View History

2022-02-14 12:13:30 +03:00
/**
* 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/scp.h
* @brief scp declarations
* @author Simone Fedele/ Matt Burt
*
* Functions in this file use the following naming conventions:-
*
* E_SCP_<msg>_REQUEST is sent by scp_send_<msg>_request()
* E_SCP_<msg>_REQUEST is parsed by scp_get_<msg>_request()
* E_SCP_<msg>_RESPONSE is sent by scp_send_<msg>_response()
* E_SCP_<msg>_RESPONSE is parsed by scp_get_<msg>_response()
*/
#ifndef SCP_H
#define SCP_H
#include "arch.h"
struct guid;
struct trans;
#include "scp_application_types.h"
/* Message codes */
enum scp_msg_code
{
E_SCP_GATEWAY_REQUEST = 1,
E_SCP_GATEWAY_RESPONSE,
E_SCP_CREATE_SESSION_REQUEST,
E_SCP_CREATE_SESSION_RESPONSE,
E_SCP_LIST_SESSIONS_REQUEST,
E_SCP_LIST_SESSIONS_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 *
scp_msgno_to_str(enum scp_msg_code n, char *buff, unsigned int buff_size);
/* Connection management facilities */
/**
* Maps a port definition to a UNIX domain socket path
* @param port Port definition (e.g. from sesman.ini). Can be "" or NULL
* @param buff Buffer for result
* @param bufflen Length of buff
*
* @return Number of chars needed for result, excluding the '\0'
*/
int
scp_port_to_unix_domain_path(const char *port, char *buff,
unsigned int bufflen);
/**
* Maps a port definition to a displayable string
* @param port Port definition (e.g. from sesman.ini). Can be "" or NULL
* @param buff Buffer for result
* @param bufflen Length of buff
*
* @return Number of chars needed for result, excluding the '\0'
*
* This differs from scp_port_to_unix_domain_path() in that the result is
* for displaying to the user (i.e. in a status message), rather than for
* connecting to. For log messages, use the result of
* scp_port_to_unix_domain_path()
*/
int
scp_port_to_display_string(const char *port, char *buff, unsigned int bufflen);
2022-02-14 12:13:30 +03:00
/**
* Connect to an SCP server
*
* @param port Port definition (e.g. from sesman.ini)
2022-02-14 12:13:30 +03:00
* @param term_func Function to poll during connection for program
* termination, or NULL for none.
* @return Initialised SCP transport
*
2022-09-03 02:48:01 +03:00
* The returned transport has the is_term member set to term_func.
2022-02-14 12:13:30 +03:00
*/
struct trans *
scp_connect(const char *port,
2022-02-14 12:13:30 +03:00
int (*term_func)(void));
/**
* Converts a standard trans connected to an SCP endpoint to an SCP transport
*
* @param trans connected endpoint
* @return != 0 for error
*
2022-09-03 02:48:01 +03:00
* The returned transport has the is_term member set to term_func.
2022-02-14 12:13:30 +03:00
*/
int
scp_init_trans(struct trans *trans);
/**
* Checks an SCP transport to see if a complete message is
* available for parsing
*
* @param trans SCP transport
* @param[out] available != 0 if a complete message is available
* @return != 0 for error
*/
int
scp_msg_in_check_available(struct trans *trans, int *available);
/**
* Waits on a single transport for an SCP 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
* scp_msg_in_check_available()
*/
int
scp_msg_in_wait_available(struct trans *trans);
/**
* Start parsing an SCP message
*
* @param trans SCP transport
* @return message in the buffer
*
* The results of calling this routine before scp_msg_in_check_available()
* states a message is available are undefined.
*
* Calling this function rests the message parsing pointer to the start
* of the message
*/
enum scp_msg_code
scp_msg_in_start(struct trans *trans);
/**
* Resets an SCP message buffer ready to receive the next message
*
* @param trans libipm transport
*/
void
scp_msg_in_reset(struct trans *trans);
/**
* Send an E_SCP_GATEWAY_REQUEST (SCP client)
*
* @param trans SCP transport
* @param username Username
* @param password Password
* @param ip_addr IP address for the client (or "" if not known)
2022-02-14 12:13:30 +03:00
* @return != 0 for error
*
* Server replies with E_SCP_GATEWAY_RESPONSE
*/
int
scp_send_gateway_request(struct trans *trans,
const char *username,
const char *password,
const char *ip_addr);
2022-02-14 12:13:30 +03:00
/**
* Parse an incoming E_SCP_GATEWAY_REQUEST message (SCP server)
*
* @param trans SCP transport
* @param[out] username Username
* @param[out] password Password
* @param[out] ip_addr IP address for the client. May be ""
2022-02-14 12:13:30 +03:00
* @return != 0 for error
*/
int
scp_get_gateway_request(struct trans *trans,
const char **username,
const char **password,
const char **ip_addr);
2022-02-14 12:13:30 +03:00
/**
* Send an E_SCP_GATEWAY_RESPONSE (SCP server)
*
* @param trans SCP transport
* @param auth_result 0 for success, PAM error code otherwise
* @return != 0 for error
*/
int
scp_send_gateway_response(struct trans *trans,
int auth_result);
/**
* Parses an incoming E_SCP_GATEWAY_RESPONSE (SCP client)
*
* @param trans SCP transport
* @param[out] auth_result 0 for success, PAM error code otherwise
* @return != 0 for error
*/
int
scp_get_gateway_response(struct trans *trans,
int *auth_result);
/* Session messages */
/**
* Send an E_SCP_CREATE_SESSION_REQUEST (SCP client)
*
* @param trans SCP transport
* @param username Username of session to create or re-connect to
* @param password Password for user
* @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 ""
* @param ip_addr IP address for the client (or "" if not known)
2022-02-14 12:13:30 +03:00
* @return != 0 for error
*
* Server replies with E_SCP_CREATE_SESSION_RESPONSE
*/
int
scp_send_create_session_request(struct trans *trans,
const char *username,
const char *password,
enum scp_session_type type,
unsigned short width,
unsigned short height,
unsigned char bpp,
const char *shell,
const char *directory,
const char *ip_addr);
2022-02-14 12:13:30 +03:00
/**
* Parse an incoming E_SCP_CREATE_SESSION_REQUEST (SCP server)
*
* @param trans SCP transport
* @param[out] username Username of session to create or re-connect to
* @param[out] password Password for user
* @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 ""
* @param[out] ip_addr IP address for the client. May be ""
2022-02-14 12:13:30 +03:00
* @return != 0 for error
*
* Returned string pointers are valid until scp_msg_in_reset() is
* called for the transport
*/
int
scp_get_create_session_request(struct trans *trans,
const char **username,
const char **password,
enum scp_session_type *type,
unsigned short *width,
unsigned short *height,
unsigned char *bpp,
const char **shell,
const char **directory,
const char **ip_addr);
2022-02-14 12:13:30 +03:00
/**
* Send an E_SCP_CREATE_SESSION_RESPONSE (SCP server)
*
* @param trans SCP transport
* @param auth_result 0 for success, PAM error code otherwise
* @param display Should be zero if authentication failed.
* @param guid Guid for session. Should be all zeros if authentication failed
*
* @return != 0 for error
*/
int
scp_send_create_session_response(struct trans *trans,
int auth_result,
int display,
const struct guid *guid);
/**
* Parse an incoming E_SCP_CREATE_SESSION_RESPONSE (SCP client)
*
* @param trans SCP transport
* @param[out] auth_result 0 for success, PAM error code otherwise
* @param[out] display Should be zero if authentication failed.
* @param[out] guid Guid for session. Should be all zeros if authentication
* failed
*
* @return != 0 for error
*/
int
scp_get_create_session_response(struct trans *trans,
int *auth_result,
int *display,
struct guid *guid);
/**
* Status of an E_SCP_LIST_SESSIONS_RESPONSE message
*/
enum scp_list_sessions_status
{
/**
* This message contains a valid session, and other messages
* will be sent
*/
E_SCP_LS_SESSION_INFO = 0,
/**
* This message indicates the end of a list of sessions. No session
* is contained in the message */
E_SCP_LS_END_OF_LIST,
/**
* Authentication failed for the user
*/
E_SCP_LS_AUTHENTICATION_FAIL = 100,
/**
* A client-side error occurred allocating memory for the session
*/
E_SCP_LS_NO_MEMORY
};
/**
* Send an E_LIST_SESSIONS_REQUEST (SCP client)
*
* @param trans SCP transport
* @param username Username
* @param password Password
* @return != 0 for error
*
* Server replies with one or more E_SCP_LIST_SESSIONS_RESPONSE
*/
int
scp_send_list_sessions_request(struct trans *trans,
const char *username,
const char *password);
/**
* Parse an incoming E_LIST_SESSIONS_REQUEST (SCP server)
*
* @param trans SCP transport
* @param[out] username Username
* @param[out] password Password
* @return != 0 for error
*/
int
scp_get_list_sessions_request(struct trans *trans,
const char **username,
const char **password);
/**
* Send an E_LIST_SESSIONS_RESPONSE (SCP server)
*
* @param trans SCP transport
* @param status Status of request
* @param info Session to send if status == E_SCL_LS_SESSION_INFO
* @return != 0 for error
*/
int
scp_send_list_sessions_response(
struct trans *trans,
enum scp_list_sessions_status status,
const struct scp_session_info *info);
/**
* Parse an incoming E_LIST_SESSIONS_RESPONSE (SCP client)
*
* @param trans SCP transport
* @param[out] status Status of request
* @param[out] info Session if status == E_SCL_LS_SESSION_INFO
* @return != 0 for error
*
* The session info is returned as a dynamically allocated structure.
* After use the structure (and its members) can be de-allocated with
* a single call to g_free()
*
* The info structures can be added to a 'struct list' with auto_free set.
* When the list is de-allocated, all the structures will be de-allocated too.
*/
int
scp_get_list_sessions_response(
struct trans *trans,
enum scp_list_sessions_status *status,
struct scp_session_info **info);
#endif /* SCP_H */