ipc.h

Go to the documentation of this file.

/*
 * Copyright 2004-2024 the Pacemaker project contributors
 *
 * The version control history for this file may have further details.
 *
 * This source code is licensed under the GNU Lesser General Public License
 * version 2.1 or later (LGPLv2.1+) WITHOUT ANY WARRANTY.
 */

#ifndef PCMK__CRM_COMMON_IPC__H
#define PCMK__CRM_COMMON_IPC__H


#include <sys/uio.h>
#include <qb/qbipcc.h>
#include <crm/common/xml.h>

#ifdef __cplusplus
extern "C" {
#endif

/*
 * Message creation utilities
 *
 * These are used for both IPC messages and cluster layer messages. However,
 * since this is public API, they stay in this header for backward
 * compatibility.
 */

// @COMPAT Make internal when we can break API backward compatibility
#define create_reply(request, xml_response_data)    \
    create_reply_adv(request, xml_response_data, __func__)

// @COMPAT Make internal when we can break API backward compatibility
xmlNode *create_reply_adv(const xmlNode *request, xmlNode *xml_response_data,
                          const char *origin);

// @COMPAT Make internal when we can break API backward compatibility
#define create_request(task, xml_data, host_to, sys_to, sys_from, uuid_from) \
    create_request_adv(task, xml_data, host_to, sys_to, sys_from, uuid_from, \
                       __func__)

// @COMPAT Make internal when we can break API backward compatibility
xmlNode *create_request_adv(const char *task, xmlNode *xml_data,
                            const char *host_to, const char *sys_to,
                            const char *sys_from, const char *uuid_from,
                            const char *origin);


/*
 * The library supports two methods of creating IPC connections. The older code
 * allows connecting to any arbitrary IPC name. The newer code only allows
 * connecting to one of the Pacemaker daemons.
 *
 * As daemons are converted to use the new model, the old functions should be
 * considered deprecated for use with those daemons. Once all daemons are
 * converted, the old functions should be officially deprecated as public API
 * and eventually made internal API.
 */

/*
 * Pacemaker daemon IPC
 */

enum pcmk_ipc_server {
    pcmk_ipc_attrd,         
    pcmk_ipc_based,         
    pcmk_ipc_controld,      
    pcmk_ipc_execd,         
    pcmk_ipc_fenced,        
    pcmk_ipc_pacemakerd,    
    pcmk_ipc_schedulerd,    
};

// NOTE: sbd (as of at least 1.5.2) uses this enum
enum pcmk_ipc_event {
    pcmk_ipc_event_connect,     

    // NOTE: sbd (as of at least 1.5.2) uses this value
    pcmk_ipc_event_disconnect,  

    // NOTE: sbd (as of at least 1.5.2) uses this value
    pcmk_ipc_event_reply,       

    pcmk_ipc_event_notify,      
};

enum pcmk_ipc_dispatch {
    pcmk_ipc_dispatch_main, 
    pcmk_ipc_dispatch_poll, 
    pcmk_ipc_dispatch_sync, 
};

// NOTE: sbd (as of at least 1.5.2) uses this
typedef struct pcmk_ipc_api_s pcmk_ipc_api_t;

typedef void (*pcmk_ipc_callback_t)(pcmk_ipc_api_t *api,
                                    enum pcmk_ipc_event event_type,
                                    crm_exit_t status,
                                    void *event_data, void *user_data);

// NOTE: sbd (as of at least 1.5.2) uses this
int pcmk_new_ipc_api(pcmk_ipc_api_t **api, enum pcmk_ipc_server server);

// NOTE: sbd (as of at least 1.5.2) uses this
void pcmk_free_ipc_api(pcmk_ipc_api_t *api);

// NOTE: sbd (as of at least 1.5.2) uses this
int pcmk_connect_ipc(pcmk_ipc_api_t *api, enum pcmk_ipc_dispatch dispatch_type);

void pcmk_disconnect_ipc(pcmk_ipc_api_t *api);

int pcmk_poll_ipc(const pcmk_ipc_api_t *api, int timeout_ms);

void pcmk_dispatch_ipc(pcmk_ipc_api_t *api);

// NOTE: sbd (as of at least 1.5.2) uses this
void pcmk_register_ipc_callback(pcmk_ipc_api_t *api, pcmk_ipc_callback_t cb,
                                void *user_data);

const char *pcmk_ipc_name(const pcmk_ipc_api_t *api, bool for_log);

bool pcmk_ipc_is_connected(pcmk_ipc_api_t *api);

int pcmk_ipc_purge_node(pcmk_ipc_api_t *api, const char *node_name,
                        uint32_t nodeid);


/*
 * Generic IPC API (to eventually be deprecated as public API and made internal)
 */

/* *INDENT-OFF* */
enum crm_ipc_flags
{
    crm_ipc_flags_none      = 0x00000000,

    crm_ipc_compressed      = 0x00000001, /* Message has been compressed */

    crm_ipc_proxied         = 0x00000100, /* _ALL_ replies to proxied connections need to be sent as events */
    crm_ipc_client_response = 0x00000200, /* A Response is expected in reply */

    // These are options for Pacemaker's internal use only (pcmk__ipc_send_*())
    crm_ipc_server_event    = 0x00010000, /* Send an Event instead of a Response */
    crm_ipc_server_free     = 0x00020000, /* Free the iovec after sending */
    crm_ipc_proxied_relay_response = 0x00040000, /* all replies to proxied connections are sent as events, this flag preserves whether the event should be treated as an actual event, or a response.*/

#if !defined(PCMK_ALLOW_DEPRECATED) || (PCMK_ALLOW_DEPRECATED == 1)
    crm_ipc_server_info     = 0x00100000, 
    crm_ipc_server_error    = 0x00200000, 
#endif
};
/* *INDENT-ON* */

typedef struct crm_ipc_s crm_ipc_t;

crm_ipc_t *crm_ipc_new(const char *name, size_t max_size);
bool crm_ipc_connect(crm_ipc_t * client);
void crm_ipc_close(crm_ipc_t * client);
void crm_ipc_destroy(crm_ipc_t * client);
void pcmk_free_ipc_event(struct iovec *event);

int crm_ipc_send(crm_ipc_t *client, const xmlNode *message,
                 enum crm_ipc_flags flags, int32_t ms_timeout, xmlNode **reply);

int crm_ipc_get_fd(crm_ipc_t * client);
bool crm_ipc_connected(crm_ipc_t * client);
int crm_ipc_ready(crm_ipc_t * client);
long crm_ipc_read(crm_ipc_t * client);
const char *crm_ipc_buffer(crm_ipc_t * client);
uint32_t crm_ipc_buffer_flags(crm_ipc_t * client);
const char *crm_ipc_name(crm_ipc_t * client);
unsigned int crm_ipc_default_buffer_size(void);

int crm_ipc_is_authentic_process(int sock, uid_t refuid, gid_t refgid,
                                 pid_t *gotpid, uid_t *gotuid, gid_t *gotgid);

// @COMPAT Make internal when we can break API backward compatibility
xmlNode *create_hello_message(const char *uuid, const char *client_name,
                              const char *major_version, const char *minor_version);

#ifdef __cplusplus
}
#endif

#endif