/* * Copyright (C) 2010-2020 Red Hat, Inc. * * Author: Steven Dake * * This file is part of libqb. * * libqb is free software: you can redistribute it and/or modify * it under the terms of the GNU Lesser General Public License as published by * the Free Software Foundation, either version 2.1 of the License, or * (at your option) any later version. * * libqb is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public License * along with libqb. If not, see . */ #ifndef QB_IPCC_H_DEFINED #define QB_IPCC_H_DEFINED /* *INDENT-OFF* */ #ifdef __cplusplus extern "C" { #endif /* *INDENT-ON* */ #include /* size_t, ssize_t */ #include /* iovec */ #include /** * @file qbipcc.h * * Client IPC API. * * @par Lifecycle of an IPC connection. * An IPC connection is made to the server with qb_ipcc_connect(). This function * connects to the server and requests channels be created for communication. * To disconnect, the client either exits or executes the function qb_ipcc_disconnect(). * * @par Synchronous communication * The function qb_ipcc_sendv_recv() sends an iovector request and receives a response. * * @par Asynchronous requests from the client * The function qb_ipcc_sendv() sends an iovector request. * The function qb_ipcc_send() sends an message buffer request. * * @par Asynchronous events from the server * The qb_ipcc_event_recv() function receives an out-of-band asynchronous message. * The asynchronous messages are queued and can provide very high out-of-band performance. * To determine when to call qb_ipcc_event_recv() the qb_ipcc_fd_get() call is * used to obtain a file descriptor used in the poll() or select() system calls. * * @example ipcclient.c * This is an example of how to use the client. */ typedef struct qb_ipcc_connection qb_ipcc_connection_t; /** * Create a connection to an IPC service. * * @param name name of the service. * @param max_msg_size biggest msg size. * @return NULL (error: see errno) or a connection object. * * @note It is recommended to do a one time check on the * max_msg_size value using qb_ipcc_verify_dgram_max_msg_size * _BEFORE_ calling the connect function when IPC_SOCKET is in use. * Some distributions while allow large message buffers to be * set on the socket, but not actually honor them because of * kernel state values. The qb_ipcc_verify_dgram_max_msg_size * function both sets the socket buffer size and verifies it by * doing a send/recv. */ qb_ipcc_connection_t* qb_ipcc_connect(const char *name, size_t max_msg_size); /** * Asynchronously connect to an IPC service * @param name name of the service. * @param max_msg_size biggest msg size. * @param connect_fd return FD to continue connection with * @return NULL (error: see errno) or a connection object. * * qb_ipcc_connect_async() returns a connection FD which * should be used added to the application's mainloop - when it is * active, qb_ipcc_connect_continue() should be called for the * connection to be finalised. * NOTE: This is NOT the same FD that is used for normal applicaion * polling. qb_ipcc_fd_get() must still be called once the connection * is established. */ qb_ipcc_connection_t * qb_ipcc_connect_async(const char *name, size_t max_msg_size, int *connect_fd); /** * Finish up an asynchonous IPC connection * @param c connection handle as returned from qb_ipcc_connect_async() * @return 0 or -errno. * * Finishes up a connection that was initiated by qb_ipcc_connect_async(), * this should only be called when the fd returned by qb_ipcc_connect_async() * becomes active, usually as a callback in the application's main loop. */ int qb_ipcc_connect_continue(struct qb_ipcc_connection * c); /** * Test kernel dgram socket buffers to verify the largest size up * to the max_msg_size value a single msg can be. Rounds down to the * nearest 1k. * * @param max_msg_size biggest msg size. * @return -1 if max size can not be detected, positive value * representing the largest single msg up to max_msg_size * that can successfully be sent over a unix dgram socket. */ int32_t qb_ipcc_verify_dgram_max_msg_size(size_t max_msg_size); /** * Disconnect an IPC connection. * * @param c connection instance */ void qb_ipcc_disconnect(qb_ipcc_connection_t* c); /** * Get the file descriptor to poll. * * @param c connection instance * @param fd (out) file descriptor to poll */ int32_t qb_ipcc_fd_get(qb_ipcc_connection_t* c, int32_t * fd); /** * Get the credentials of the server process * * * @param c connection instance * @param pid PID of the server we are connected to * @param uid UID of the server we are connected to * @param gid GID of the server we are connected to */ int32_t qb_ipcc_auth_get(qb_ipcc_connection_t* c, pid_t *pid, uid_t *uid, gid_t *gid); /** * Set the maximum allowable flowcontrol value. * * @note the default is 1 * * @param c connection instance * @param max the max allowable flowcontrol value (1 or 2) */ int32_t qb_ipcc_fc_enable_max_set(qb_ipcc_connection_t * c, uint32_t max); /** * Send a message. * * @param c connection instance * @param msg_ptr pointer to a message to send * @param msg_len the size of the message * @return (size sent, -errno == error) * * @note the msg_ptr must include a qb_ipc_request_header at * the top of the message. The server will read the size field * to determine how much to recv. */ ssize_t qb_ipcc_send(qb_ipcc_connection_t* c, const void *msg_ptr, size_t msg_len); /** * Send a message (iovec). * * @param c connection instance * @param iov pointer to an iovec struct to send * @param iov_len the number of iovecs used * @return (size sent, -errno == error) * * @note the iov[0] must be a qb_ipc_request_header. The server will * read the size field to determine how much to recv. */ ssize_t qb_ipcc_sendv(qb_ipcc_connection_t* c, const struct iovec* iov, size_t iov_len); /** * Receive a response. * * @param c connection instance * @param msg_ptr pointer to a message buffer to receive into * @param msg_len the size of the buffer * @param ms_timeout max time to wait for a response * @return (size recv'ed, -errno == error) * * @note that msg_ptr will include a qb_ipc_response_header at * the top of the message. */ ssize_t qb_ipcc_recv(qb_ipcc_connection_t* c, void *msg_ptr, size_t msg_len, int32_t ms_timeout); /** * This is a convenience function that simply sends and then recvs. * * @param c connection instance * @param iov pointer to an iovec struct to send * @param iov_len the number of iovecs used * @param msg_ptr pointer to a message buffer to receive into * @param msg_len the size of the buffer * @param ms_timeout max time to wait for a response * * @note the iov[0] must include a qb_ipc_request_header at * the top of the message. The server will read the size field * to determine how much to recv. * @note that msg_ptr will include a qb_ipc_response_header at * the top of the message. * * @see qb_ipcc_sendv() qb_ipcc_recv() */ ssize_t qb_ipcc_sendv_recv(qb_ipcc_connection_t *c, const struct iovec *iov, uint32_t iov_len, void *msg_ptr, size_t msg_len, int32_t ms_timeout); /** * Receive an event. * * @param c connection instance * @param msg_ptr pointer to a message buffer to receive into * @param msg_len the size of the buffer * @param ms_timeout time in milliseconds to wait for a message * 0 == no wait, negative == block, positive == wait X ms. * @return size of the message or error (-errno) * * @note that msg_ptr will include a qb_ipc_response_header at * the top of the message. */ ssize_t qb_ipcc_event_recv(qb_ipcc_connection_t* c, void *msg_ptr, size_t msg_len, int32_t ms_timeout); /** * Associate a "user" pointer with this connection. * * @param context the point to associate with this connection. * @param c connection instance * @see qb_ipcc_context_get() */ void qb_ipcc_context_set(qb_ipcc_connection_t *c, void *context); /** * Get the context (set previously) * * @param c connection instance * @return the context * @see qb_ipcc_context_set() */ void *qb_ipcc_context_get(qb_ipcc_connection_t *c); /** * Is the connection connected? * * @param c connection instance * @retval QB_TRUE when connected * @retval QB_FALSE when not connected */ int32_t qb_ipcc_is_connected(qb_ipcc_connection_t *c); /** * What is the actual buffer size used after the connection. * * @note The buffer size is guaranteed to be at least the size * of the value given in qb_ipcc_connect, but it is possible * the server will enforce a larger size depending on the * implementation. If the server side is known to enforce * a buffer size, use this function after the client connection * is established to retrieve the buffer size in use. It is * important for the client side to know the buffer size in use * so the client can successfully retrieve large server events. * * @param c connection instance * @retval connection size in bytes or -error code */ int32_t qb_ipcc_get_buffer_size(qb_ipcc_connection_t * c); /* *INDENT-OFF* */ #ifdef __cplusplus } #endif /* *INDENT-ON* */ #endif /* QB_IPCC_H_DEFINED */