/** * Copyright (C) 2022 Matt Burt, 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/libipm.h * @brief Inter-Process Messaging building and parsing - public declarations * * The functions in this file are inspired by the D-Bus type system * (see https://dbus.freedesktop.org/doc/dbus-specification.html), * and the sd-bus library API. */ #if !defined(LIBIPM_H) #define LIBIPM_H #if defined(HAVE_CONFIG_H) #include #endif #include "arch.h" #include "libipm_facilities.h" struct trans; /** * Fixed-size block descriptor for sending blocks of data using libipm * * Use with the type code 'B' * * See the descriptions of libipm_msg_out_append() and libipm_msg_in_parse() * for instructions on how to use this type. */ struct libipm_fsb { void *data; unsigned int datalen; }; /** * Status code for library calls * * These are mainly intended so that the test suite can check the expected * codepath has been followed. * * Wrappers around libipm may assume success is 0, and anything else * is an error. */ enum libipm_status { E_LI_SUCCESS = 0, E_LI_PROGRAM_ERROR, /***< Programming error */ E_LI_NO_MEMORY, /***< Memory allocation failure */ E_LI_UNSUPPORTED_TYPE, /***< Specified type code is unsupported */ E_LI_UNIMPLEMENTED_TYPE, /***< Specified type code is unimplemented */ E_LI_UNEXPECTED_TYPE, /***< Encountered unexpected type on input */ E_LI_BUFFER_OVERFLOW, /***< End of buffer reached unexpectedly */ E_LI_BAD_VALUE, /***< Specified (or incoming) value is out of range */ E_LI_BAD_HEADER, /***< Bad incoming message header */ E_LI_TRANSPORT_ERROR /***< Error detected at the transport level */ }; /* Flags values for libipm_[set/clear]_flags() */ /** * Input buffer contains sensitive information and must be * erased by libipm_msg_in_reset(). The flag is one-shot, and * is cleared after use. * * There is no corresponding flag for the output buffer - * use libipm_msg_out_erase() explicitly */ #define LIBIPM_E_MSG_IN_ERASE_AFTER_USE (1u<<0) /** * Prepare a standard 'struct trans' for use with libipm * * @param trans libipm transport * @param facility Facility number from libipm_facilities.h * @param msgno_to_str Function to turn a message number into a string * @return != 0 for error. * * The msgno_to_str() function is used for error logging. If the routine * is not specified, or the routine returns NULL, a numeric code is * logged instead. */ enum libipm_status libipm_init_trans(struct trans *trans, enum libipm_facility facility, const char *(*msgno_to_str)(unsigned short msgno)); /** * Set the flag(s) specified for the transport * @param trans libipm transport * @param flags flags to set. Multiple flags should be or'd together. */ void libipm_set_flags(struct trans *trans, unsigned int flags); /** * Clear the flag(s) specified for the transport * @param trans libipm transport * @param flags flags to clear. Multiple flags should be or'd together. */ void libipm_clear_flags(struct trans *trans, unsigned int flags); /** * Initialise an output message * * @param trans libipm transport * @param msgno message number * @param format a description of any arguments to add to the buffer, or * NULL if no arguments are to be added at this time. * * See libipm_msg_out_append() for details of the format string. The format * string is followed immediately by the arguments it describes */ enum libipm_status libipm_msg_out_init(struct trans *trans, unsigned short msgno, const char *format, ...); /** * Append more arguments to an output message * * @param trans libipm transport * @param format a description of any arguments to add to the buffer. * @param != 0 if an error occurs * * The format string is followed immediately by the arguments it * describes. The format string may contain these characters (from the * D-Bus type system):- * * Char | C Type | Description * ---- |------ | ----------- * y |uint8_t | Unsigned 8-bit integer * b |int | Boolean value (see below) * n |int16_t | Signed (two's complement) 16-bit integer * q |uint16_t | Unsigned 16-bit integer * i |int32_t | Signed (two's complement) 32-bit integer * u |uint32_t | Unsigned 32-bit integer * x |int64_t | Signed (two's complement) 64-bit integer * t |uint64_t | Unsigned 64-bit integer * s |char * | NULL-terminated string * d | - | (reserved) * h | - | (reserved) * o | - | (reserved) * g | - | (reserved) * * For the 'b' type, only values 0 and 1 are allowed. Other values * generate an error. * * The following additions to the D-Bus type system are also supported:- * * Char |C Type | Description * -----|------ | ----------- * B |const struct libipm_fsb * | Fixed-size block pointer * * For the 'B' type, pass in the address of a descriptor containing the * address and size of the object. The object is copied to the output * stream, along with its length. */ enum libipm_status libipm_msg_out_append(struct trans *trans, const char *format, ...); /** * Marks a message as complete and ready for transmission * * @param trans libipm transport */ void libipm_msg_out_mark_end(struct trans *trans); /** * Convenience sending function * * Constructs a simple message and sends it immediately using * libipm_msg_out_init() / libipm_msg_out_mark_end() and * trans_force_write() * * @param trans libipm transport * @param msgno message number * @param format a description of any arguments to add to the buffer, or * NULL if no arguments are to be added at this time. * * See libipm_msg_out_append() for details of the format string. The format * string is followed immediately by the arguments it describes */ enum libipm_status libipm_msg_out_simple_send(struct trans *trans, unsigned short msgno, const char *format, ...); /** * Erase (rather than just ignore) the contents of an output buffer * * Use after sending a message containing data which should not be * kept in memory (e.g. passwords)` * @param trans libipm transport */ void libipm_msg_out_erase(struct trans *trans); /** * Checks a transport to see if a complete libipm message is * available for parsing * * @param trans libipm transport * @param[out] available != 0 if a complete message is available * @return != 0 for error */ enum libipm_status libipm_msg_in_check_available(struct trans *trans, int *available); /** * Waits on a single transport for a libipm 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 * libipm_msg_in_check_available() */ enum libipm_status libipm_msg_in_wait_available(struct trans *trans); /** * Start parsing a message * * @param trans libipm transport * @return message number in the buffer * * The results of calling this routine after a call to * libipm_msg_in_reset() and before a successful call to * libipm_msg_in_check_available() (or libipm_msg_wait_available()) * are undefined. * * Calling this function resets the message parsing pointer to the start * of the message */ unsigned short libipm_msg_in_start(struct trans *trans); /** * Returns a letter corresponding to the next available type in the * input stream. * * @param trans libipm transport * @return letter of the type, '\0' for end of message, or '?' for * an unrecognised type */ char libipm_msg_in_peek_type(struct trans *trans); /** * Reads arguments from an input message * * @param trans libipm transport * @param format a description of the arguments to read from the buffer. * @param != 0 if an error occurs * * The format string is followed immediately by the arguments it * describes. The format string may contain these characters (from the * D-Bus type system):- * * Char | C Type | Description * ---- | ------ | ----------- * y | uint8_t * | Unsigned 8-bit integer * b | int * | Boolean value (0 or 1 only) * n | int16_t * | Signed (two's complement) 16-bit integer * q | uint16_t * | Unsigned 16-bit integer * i | int32_t * | Signed (two's complement) 32-bit integer * u | uint32_t * | Unsigned 32-bit integer * x | int64_t * | Signed (two's complement) 64-bit integer * t | uint64_t * | Unsigned 64-bit integer * s | char ** | NULL-terminated string * d | - | (reserved) * h | - | (reserved) * o | - | (reserved) * g | - | (reserved) * * The following additions to the D-Bus type system are also supported:- * * Char | C Type | Description * -----| ------ | ----------- * B | const struct libipm_fsb * | Fixed-size block pointer * * For the 's' type, a pointer into the string in the input buffer is * returned. This pointer will only be valid until the next call to * libipm_msg_in_reset() * * For the 'B' type, pass in the address of an initialised descriptor * containing the address and size of the object to copy the data * to. The size in the descriptor must match the size of the object * on-the-wire. Unlike 's', the data is copied out of the input buffer. * */ enum libipm_status libipm_msg_in_parse(struct trans *trans, const char *format, ...); /** * Resets a message buffer ready to receive the next message * * If the LIBIPM_E_MSG_IN_ERASE_AFTER_USE flag is set for the transport, * the entire buffer is erased, and the flag is cleared * * @param trans libipm transport */ void libipm_msg_in_reset(struct trans *trans); #endif /* LIBIPM_H */