331 lines
13 KiB
C
Executable File
331 lines
13 KiB
C
Executable File
/*
|
|
* Copyright (c) 2013-2016, Wind River Systems, Inc.
|
|
*
|
|
* Redistribution and use in source and binary forms, with or without modification, are
|
|
* permitted provided that the following conditions are met:
|
|
*
|
|
* 1) Redistributions of source code must retain the above copyright notice,
|
|
* this list of conditions and the following disclaimer.
|
|
*
|
|
* 2) Redistributions in binary form must reproduce the above copyright notice,
|
|
* this list of conditions and the following disclaimer in the documentation and/or
|
|
* other materials provided with the distribution.
|
|
*
|
|
* 3) Neither the name of Wind River Systems nor the names of its contributors may be
|
|
* used to endorse or promote products derived from this software without specific
|
|
* prior written permission.
|
|
*
|
|
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
|
|
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
|
* CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
|
|
* USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
*/
|
|
#ifndef __GUEST_HERATBEAT_API_H__
|
|
#define __GUEST_HEARTBEAT_API_H__
|
|
|
|
#include <stdbool.h>
|
|
|
|
#include "guest_api_types.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
#define GUEST_HEARTBEAT_API_APPLICATION_NAME_MAX 40
|
|
#define GUEST_HEARTBEAT_API_LOG_MAX 192
|
|
|
|
typedef enum {
|
|
|
|
GUEST_HEARTBEAT_API_ACTION_UNKNOWN,
|
|
GUEST_HEARTBEAT_API_ACTION_NONE,
|
|
GUEST_HEARTBEAT_API_ACTION_REBOOT,
|
|
GUEST_HEARTBEAT_API_ACTION_STOP,
|
|
GUEST_HEARTBEAT_API_ACTION_LOG,
|
|
GUEST_HEARTBEAT_API_ACTION_MAX,
|
|
} GuestHeartbeatApiActionT;
|
|
|
|
typedef enum {
|
|
GUEST_HEARTBEAT_API_EVENT_UNKNOWN,
|
|
GUEST_HEARTBEAT_API_EVENT_STOP,
|
|
GUEST_HEARTBEAT_API_EVENT_REBOOT,
|
|
GUEST_HEARTBEAT_API_EVENT_SUSPEND,
|
|
GUEST_HEARTBEAT_API_EVENT_PAUSE,
|
|
GUEST_HEARTBEAT_API_EVENT_UNPAUSE,
|
|
GUEST_HEARTBEAT_API_EVENT_RESUME,
|
|
GUEST_HEARTBEAT_API_EVENT_RESIZE_BEGIN,
|
|
GUEST_HEARTBEAT_API_EVENT_RESIZE_END,
|
|
GUEST_HEARTBEAT_API_EVENT_LIVE_MIGRATE_BEGIN,
|
|
GUEST_HEARTBEAT_API_EVENT_LIVE_MIGRATE_END,
|
|
GUEST_HEARTBEAT_API_EVENT_COLD_MIGRATE_BEGIN,
|
|
GUEST_HEARTBEAT_API_EVENT_COLD_MIGRATE_END,
|
|
GUEST_HEARTBEAT_API_EVENT_MAX,
|
|
} GuestHeartbeatApiEventT;
|
|
|
|
typedef enum {
|
|
GUEST_HEARTBEAT_API_NOTIFY_TYPE_UNKNOWN,
|
|
GUEST_HEARTBEAT_API_NOTIFY_TYPE_REVOCABLE, // vote on an action
|
|
GUEST_HEARTBEAT_API_NOTIFY_TYPE_IRREVOCABLE, // notification of an action
|
|
GUEST_HEARTBEAT_API_NOTIFY_TYPE_MAX,
|
|
} GuestHeartbeatApiNotifyTypeT;
|
|
|
|
typedef enum {
|
|
//
|
|
GUEST_HEARTBEAT_API_VOTE_RESULT_UNKNOWN,
|
|
GUEST_HEARTBEAT_API_VOTE_RESULT_ACCEPT, // vote to accept an action
|
|
GUEST_HEARTBEAT_API_VOTE_RESULT_REJECT, // vote to reject an action
|
|
GUEST_HEARTBEAT_API_VOTE_RESULT_COMPLETE, // ready for action
|
|
GUEST_HEARTBEAT_API_VOTE_RESULT_MAX,
|
|
} GuestHeartbeatApiVoteResultT;
|
|
|
|
// ****************************************************************************
|
|
// Guest Heartbeat API - Initialization Data
|
|
// =========================================
|
|
// Description:
|
|
// Configuration data used on registration.
|
|
//
|
|
// Fields:
|
|
// application_name name of the application, used for logging
|
|
// heartbeat_interval_ms the interval for heartbeat challenges
|
|
// vote_secs maximum time to wait for a vote to complete
|
|
// shutdown_notice_secs maximum time to wait for a shutdown prep
|
|
// suspend_notice_secs maximum time to wait for a suspend prep
|
|
// resume_notice_secs maximum time to wait for a resume prep
|
|
// corrective_action corrective action on heartbeat timeouts
|
|
//
|
|
// Note: minimum heartbeat interval is 400 milliseconds. Anything below this
|
|
// interval will cause the registration to be rejected.
|
|
//
|
|
typedef struct {
|
|
char application_name[GUEST_HEARTBEAT_API_APPLICATION_NAME_MAX];
|
|
int heartbeat_interval_ms;
|
|
int vote_secs;
|
|
int shutdown_notice_secs;
|
|
int suspend_notice_secs;
|
|
int resume_notice_secs;
|
|
GuestHeartbeatApiActionT corrective_action;
|
|
} GuestHeartbeatApiInitDataT;
|
|
// ****************************************************************************
|
|
|
|
// ****************************************************************************
|
|
// Guest Heartbeat API - Register State Callback
|
|
// =============================================
|
|
// Description:
|
|
// Called when the registration with the Guest-Client changes. Situations
|
|
// this callback can be invoked are the following:
|
|
// - Guest-Client accepts the registration,
|
|
// - Guest-Client rejects the registration, and
|
|
// - Guest-Client connection fails.
|
|
//
|
|
// If the registration state is False, the application needs to register
|
|
// again with the Guest-Client.
|
|
//
|
|
// Parameters:
|
|
// state the registration state of the application.
|
|
//
|
|
typedef void (*GuestHeartbeatApiRegisterStateCallbackT)
|
|
(bool state);
|
|
// ****************************************************************************
|
|
|
|
// ****************************************************************************
|
|
// Guest Heartbeat API - Health Check Callback
|
|
// ===========================================
|
|
// Description:
|
|
// Called by the Guest-Client to request the current health of the
|
|
// application.
|
|
//
|
|
// Parameters:
|
|
// health the health of the application
|
|
// corrective_action the corrective action to be taken when unhealthy
|
|
// log_msg an indication of why the application is unhealthy.
|
|
//
|
|
typedef void (*GuestHeartbeatApiHealthCheckCallbackT)
|
|
(bool* health, GuestHeartbeatApiActionT* corrective_action,
|
|
char log_msg[]);
|
|
// ****************************************************************************
|
|
|
|
// ****************************************************************************
|
|
// Guest Heartbeat API - Action Notify Callback
|
|
// ============================================
|
|
// Description:
|
|
// Called when the Guest-Client wants to notify the application of an
|
|
// action. The notification type indicates if this is a vote or a
|
|
// notification.
|
|
//
|
|
// Parameters:
|
|
// invocation_id the unique identifier for the action.
|
|
// event the type of event for the action.
|
|
// notify_type the type of notification for the action.
|
|
//
|
|
typedef void (*GuestHeartbeatApiActionNotifyCallbackT)
|
|
(int invocation_id, GuestHeartbeatApiEventT event,
|
|
GuestHeartbeatApiNotifyTypeT notify_type);
|
|
// ****************************************************************************
|
|
|
|
typedef struct {
|
|
GuestHeartbeatApiRegisterStateCallbackT register_state;
|
|
GuestHeartbeatApiHealthCheckCallbackT health_check;
|
|
GuestHeartbeatApiActionNotifyCallbackT action_notify;
|
|
} GuestHeartbeatApiCallbacksT;
|
|
|
|
// ****************************************************************************
|
|
// Guest Heartbeat API - Action String
|
|
// ===================================
|
|
extern const char* guest_heartbeat_api_action_str(
|
|
GuestHeartbeatApiActionT action );
|
|
// ****************************************************************************
|
|
|
|
// ****************************************************************************
|
|
// Guest Heartbeat API - Event String
|
|
// ==================================
|
|
extern const char* guest_heartbeat_api_event_str(
|
|
GuestHeartbeatApiEventT event );
|
|
// ****************************************************************************
|
|
|
|
// ****************************************************************************
|
|
// Guest Heartbeat API - Notify String
|
|
// ===================================
|
|
extern const char* guest_heartbeat_api_notify_str(
|
|
GuestHeartbeatApiNotifyTypeT notify );
|
|
// ****************************************************************************
|
|
|
|
// ****************************************************************************
|
|
// Guest Heartbeat API - Vote Result String
|
|
// ========================================
|
|
extern const char* guest_heartbeat_api_vote_result_str(
|
|
GuestHeartbeatApiVoteResultT vote_result );
|
|
// ****************************************************************************
|
|
|
|
// ****************************************************************************
|
|
// Guest Heartbeat API - Register
|
|
// ==============================
|
|
// Description:
|
|
// Sends a registration request to the Guest-Client. A try-again can be
|
|
// returned which indicates that registration should be attempted again
|
|
// at a later time.
|
|
//
|
|
// Parameters:
|
|
// init_data configuration parameters and timeout values for
|
|
// this application.
|
|
//
|
|
// Returns:
|
|
// GUEST_API_OKAY on success, GUEST_API_TRY_AGAIN if Guest-Client could
|
|
// not be reached, otherwise failure.
|
|
//
|
|
extern GuestApiErrorT guest_heartbeat_api_register(
|
|
GuestHeartbeatApiInitDataT* init_data );
|
|
// ****************************************************************************
|
|
|
|
// ****************************************************************************
|
|
// Guest Heartbeat API - Deregister
|
|
// ================================
|
|
// Description:
|
|
// Sends a deregister to the Guest-Client.
|
|
//
|
|
// Parameters:
|
|
// log_msg indication of the reason for the de-registration.
|
|
//
|
|
// Returns:
|
|
// GUEST_API_OKAY on success, otherwise failure.
|
|
//
|
|
extern GuestApiErrorT guest_heartbeat_api_deregister( char log_msg[] );
|
|
// ****************************************************************************
|
|
|
|
// ****************************************************************************
|
|
// Guest Heartbeat API - Send Action Response
|
|
// ==========================================
|
|
// Description:
|
|
// Sends an action response to the Guest-Client indicating the action
|
|
// is accepted, rejected or completed.
|
|
//
|
|
// Parameters:
|
|
// invocation_id the unique identifier from the action callback.
|
|
// event the type of event from the action callback.
|
|
// notify_type the type of notification from the action callback.
|
|
// vote_result indication of acceptance of the action.
|
|
// log_msg an indication of why the action was rejected.
|
|
//
|
|
// Returns:
|
|
// GUEST_API_OKAY on success, otherwise failure.
|
|
//
|
|
extern GuestApiErrorT guest_heartbeat_api_send_action_response(
|
|
int invocation_id, GuestHeartbeatApiEventT event,
|
|
GuestHeartbeatApiNotifyTypeT notify_type,
|
|
GuestHeartbeatApiVoteResultT vote_result, char log_msg[] );
|
|
// ****************************************************************************
|
|
|
|
// ****************************************************************************
|
|
// Guest Heartbeat API - Dispatch
|
|
// ==============================
|
|
// Description:
|
|
// Called when the selection object returned by guest_heartbeat_api_get_selobj
|
|
// becomes readable.
|
|
//
|
|
// Parameters:
|
|
// selobj the selection object that has become readable.
|
|
//
|
|
// Returns:
|
|
// Nothing
|
|
//
|
|
extern void guest_heartbeat_api_dispatch( int selobj );
|
|
// ****************************************************************************
|
|
|
|
// ****************************************************************************
|
|
// Guest Heartbeat API - Get Selection Object
|
|
// ==========================================
|
|
// Description:
|
|
// Returns a selection object that can be used with poll or select.
|
|
//
|
|
// Parameters:
|
|
// None
|
|
//
|
|
// Returns:
|
|
// A valid selection object, otherwise -1.
|
|
//
|
|
extern int guest_heartbeat_api_get_selobj( void );
|
|
// ****************************************************************************
|
|
|
|
// ****************************************************************************
|
|
// Guest Heartbeat API - Initialize
|
|
// ================================
|
|
// Description:
|
|
// Initialize the Guest Heartbeat API library for use.
|
|
//
|
|
// Parameters:
|
|
// callbacks a listing of callbacks for receiving registration
|
|
// state changes, health checks, and action notifications
|
|
// (all are required to be non-NULL).
|
|
//
|
|
// Returns:
|
|
// GUEST_API_OKAY on success, otherwise failure.
|
|
//
|
|
extern GuestApiErrorT guest_heartbeat_api_initialize(
|
|
GuestHeartbeatApiCallbacksT* callbacks );
|
|
// ****************************************************************************
|
|
|
|
// ****************************************************************************
|
|
// Guest Heartbeat API - Finalize
|
|
// ==============================
|
|
// Description:
|
|
// Finalize the Guest Heartbeat API library.
|
|
//
|
|
// Parameters:
|
|
// None
|
|
//
|
|
// Returns:
|
|
// GUEST_API_OKAY on success, otherwise failure.
|
|
//
|
|
extern GuestApiErrorT guest_heartbeat_api_finalize( void );
|
|
// ****************************************************************************
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* __GUEST_HEARTBEAT_API_H__ */
|