YControl core functions are used by the application to control and integrate with the YControl protocol handler. More...

Collaboration diagram for Core Functions:

Functions
status_t	ycontrol_init (int argc, char argv[], const xmlChar subsys_id)
	Initialize the YControl library. More...

status_t	ycontrol_init_ex (int argc, char argv[], const xmlChar subsys_id, boolean is_standby)
	Initialize the YControl library. More...

status_t	ycontrol_init_ex2 (int argc, char argv[], const xmlChar subsys_id, boolean is_standby, boolean quiet_mode)
	Setup global vars before accepting any requests; extended 2. More...

status_t	ycontrol_init2 (void)
	Phase 2 initialization. More...

status_t	ycontrol_init2_ha (const char server_id, const char server_addr, uint16 server_port)
	Phase 2 initialization for HA. More...

void	ycontrol_init2_ha_thd (thd_tcb_t *tcb)
	Setup scb->tcb for ycontrol session. More...

void	ycontrol_cleanup (void)
	Cleanup ycontrol layer. More...

void	ycontrol_cleanup_ex (boolean do_ncx_cleanup)
	Cleanup ycontrol layer (extended) More...

status_t	ycontrol_check_io (void)
	Check for input/output. More...

boolean	ycontrol_is_ready (void)
	Check if the ycontrol ready is up and ready to be used. More...

void	ycontrol_request_shutdown (void)
	Request a control message handler shutdown. More...

boolean	ycontrol_shutdown_requested (void)
	Check if a control message handler shutdown is in progress. More...

status_t	ycontrol_register_service (const xmlChar *service_name, ycontrol_service_start_t service_start, ycontrol_service_stop_t service_stop, ycontrol_service_msg_rcvr_t service_rcvr, ycontrol_service_shutdown_t service_shut)
	Register a specific service with the YumaPro control message manager. More...

status_t	ycontrol_register_service2 (const xmlChar *service_name, ycontrol_service_start_t service_start, ycontrol_service_stop_t service_stop, ycontrol_service_msg_rcvr_t service_rcvr, ycontrol_service_shutdown_t service_shut, ycontrol_service_reconnect_t service_reconnect)
	Register a specific service with the YumaPro control message manager Add a reconnect callback. More...

void	ycontrol_unregister_service (const xmlChar *service_name)
	Unregister a specific service. More...

void	ycontrol_service_start (void)
	Start the registered services. More...

void	ycontrol_service_stop (void)
	Stop the registered services. More...

obj_template_t *	ycontrol_get_service_object (const xmlChar *service_name)
	Get the service object from the payload container. More...

status_t	ycontrol_send (const xmlChar service_id, uint32 msgid, ycontrol_msgtype_t msgtype, val_value_t *service_payload, status_t msg_status)
	Send a YControl message. More...

status_t	ycontrol_send_ex (const xmlChar service_id, uint32 msgid, ycontrol_msgtype_t msgtype, val_value_t service_payload, status_t msg_status, const xmlChar txid_str)
	Send a YControl message (extended) More...

status_t	ycontrol_send_ex2 (const xmlChar service_id, uint32 msgid, ycontrol_msgtype_t msgtype, val_value_t service_payload, status_t msg_status, boolean with_origin, const xmlChar txid_str)
	Send a YControl message (extended2) More...

status_t	ycontrol_send_error (const xmlChar service_id, uint32 msgid, status_t msg_status, uint32 error_index, const xmlChar error_message, const xmlChar txid_str)
	Send a YControl <error> message. More...

status_t	ycontrol_send_ok (const xmlChar service_id, uint32 msgid, const xmlChar *txid_str)
	Send a YControl <ok> message. More...

boolean	ycontrol_dispatch_msg (ses_cb_t *scb)
	Find the appropriate service handler and call it with the incoming message from the server. More...

void	ycontrol_setup_reconnect (void)
	Setup the YControl profile to reconnect after the retry interval with the incoming message from the server. More...

boolean	ycontrol_shutdown_now (void)
	Check if the YControl subsystem has shut down because a <shutdown-event> was received from the server. More...

void	ycontrol_set_timer_handler (ycontrol_timer_handler_t timer_handler)
	Set the timer callback handler. More...

void	ycontrol_set_retry_interval (int retry_int)
	Set the re-connect retry interval. More...

const xmlChar *	ycontrol_get_subsys_id (void)
	Get the subsystem ID string. More...

void	ycontrol_set_retry_limit (uint16 retry_limit)
	Set the re-connect retry limit. More...

status_t	ycontrol_set_server_root (const char *server_root)
	Set the server-root when running in Multi-Instance Mode. More...

void	ycontrol_service_reconnect (void)
	Start the main server reconnect for the registered services. More...

Detailed Description

YControl core functions are used by the application to control and integrate with the YControl protocol handler.

Each YControl session is between one subsystem and one main server.

Most functions in this module are user APIs for subsystem use only!

Function Documentation

◆ ycontrol_check_io()

status_t ycontrol_check_io ( void )

Check for input/output.

Called from application to process any incoming YControl messages.

Returns: status

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ycontrol_cleanup()

void ycontrol_cleanup ( void )

Cleanup ycontrol layer.

Called by the application to cleanup resources. Must call if ycontrol_init function variant called.

Here is the call graph for this function:

◆ ycontrol_cleanup_ex()

void ycontrol_cleanup_ex ( boolean do_ncx_cleanup )

Cleanup ycontrol layer (extended)

Called by the application to cleanup resources. Must call if ycontrol_init function variant called. FUNCTION ycontrol_cleanup_ex

Cleanup all vars before exit

Parameters

do_ncx_cleanup TRUE to cleanup NCX

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ycontrol_dispatch_msg()

boolean ycontrol_dispatch_msg ( ses_cb_t * scb )

Find the appropriate service handler and call it with the incoming message from the server.

Parameters

scb	session control block containing the xmlreader set at the start of an incoming message.

Returns: TRUE if scb is still valid
FALSE if scb has been deleted during this call

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ycontrol_get_service_object()

obj_template_t * ycontrol_get_service_object ( const xmlChar * service_name )

Get the service object from the payload container.

Parameters

service_name name of service to find

Returns: pointer to object template; NULL if not found

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ycontrol_get_subsys_id()

const xmlChar * ycontrol_get_subsys_id ( void )

Get the subsystem ID string.

Returns: pointer to the subsystem ID string

◆ ycontrol_init()

status_t ycontrol_init	(	int	argc,
		char *	argv[],
		const xmlChar *	subsys_id
	)

Initialize the YControl library.

Setup global vars before accepting any requests. Process all the CLI parameters. There is no .conf file for a subsystem.

Parameters

argc	argument count
argv	argument array
subsys_id	sub-system identifier

Returns: status: 0 OK

Here is the call graph for this function:

◆ ycontrol_init2()

status_t ycontrol_init2 ( void )

Phase 2 initialization.

Setup connection to server.

Returns: status

Here is the call graph for this function:

◆ ycontrol_init2_ha()

status_t ycontrol_init2_ha	(	const char *	server_id,
		const char *	server_addr,
		uint16	server_port
	)

Phase 2 initialization for HA.

Setup connection to server with YP-HA Standby Role support The main server connection will be to the main server on another system, not the server expected to be found on this system.

Parameters

server_id	server ID to use in registration to main server
server_addr	host address of the main server to connect to
server_port	TCP port of the main server to connect to

Returns: status

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ycontrol_init2_ha_thd()

void ycontrol_init2_ha_thd ( thd_tcb_t * tcb )

Setup scb->tcb for ycontrol session.

Only present if PTHREADS=1.

Parameters

tcb	tcb to assign to the ycontrol session

◆ ycontrol_init_ex()

status_t ycontrol_init_ex	(	int	argc,
		char *	argv[],
		const xmlChar *	subsys_id,
		boolean	is_standby
	)

Initialize the YControl library.

Extended for YP-HA.

Setup global vars before accepting any requests. Process all the CLI parameters. There is no .conf file for a subsystem.

Parameters

argc	argument count
argv	argument array
subsys_id	default sub-system identifier if no –subsys-id CLI parm is found
is_standby	true if agt_yp_ha_standby is calling; this will cause ycontrol_signal to be skipped

Returns: status: 0 OK

Here is the call graph for this function:

◆ ycontrol_init_ex2()

status_t ycontrol_init_ex2	(	int	argc,
		char *	argv[],
		const xmlChar *	subsys_id,
		boolean	is_standby,
		boolean	quiet_mode
	)

Setup global vars before accepting any requests; extended 2.

Setup global vars before accepting any requests. Process all the CLI parameters. There is no .conf file for a subsystem.

Parameters

argc	argument count
argv	argument array
subsys_id	default sub-system identifier if no –subsys-id CLI parm is found
is_standby	true if agt_yp_ha_standby is calling; this will cause ycontrol_signal to be skipped
quiet_mode	true: do not log_info starting ycontrol false: normal init messages

Returns: status: 0 OK

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ycontrol_is_ready()

boolean ycontrol_is_ready ( void )

Check if the ycontrol ready is up and ready to be used.

Returns: TRUE if ready; FALSE if not

◆ ycontrol_register_service()

status_t ycontrol_register_service	(	const xmlChar *	service_name,
		ycontrol_service_start_t	service_start,
		ycontrol_service_stop_t	service_stop,
		ycontrol_service_msg_rcvr_t	service_rcvr,
		ycontrol_service_shutdown_t	service_shut
	)

Register a specific service with the YumaPro control message manager.

Officially only YumaPro services are supported but the YControl layer does not check. All callback functions must be provided . Only the receiver callback is technically required to do anything. It MUST send a subsys-response if a server-request is received.

Parameters

service_name	unique name of the service
service_start	service start callback
service_stop	service stop callback
service_rcvr	Message receiver callback
service_shut	service shutdown callback

Returns: status

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ycontrol_register_service2()

status_t ycontrol_register_service2	(	const xmlChar *	service_name,
		ycontrol_service_start_t	service_start,
		ycontrol_service_stop_t	service_stop,
		ycontrol_service_msg_rcvr_t	service_rcvr,
		ycontrol_service_shutdown_t	service_shut,
		ycontrol_service_reconnect_t	service_reconnect
	)

Register a specific service with the YumaPro control message manager Add a reconnect callback.

Officially only YumaPro services are supported but the YControl layer does not check.

All callback functions need to be provided except service_reconnect. Ycontrol does not check if these callbacks are present.

Only the receiver callback is technically required to do anything. It MUST send a subsys-response if a server-request is received.

Parameters

service_name	unique name of the service
service_start	service start callback
service_stop	service stop callback
service_rcvr	Message receiver callback
service_shut	service shutdown callback
service_reconnect	service reconnect callback (may be NULL)

Returns: status

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ycontrol_request_shutdown()

void ycontrol_request_shutdown ( void )

Request a control message handler shutdown.

This is the correct way to shutdown YControl from the application.

Here is the caller graph for this function:

◆ ycontrol_send()

status_t ycontrol_send	(	const xmlChar *	service_id,
		uint32 *	msgid,
		ycontrol_msgtype_t	msgtype,
		val_value_t *	service_payload,
		status_t	msg_status
	)

Send a YControl message.

Parameters

	service_id	service sending this message
[out]	msgid	address of message ID; for response this is non-zero *msgid set to the message ID assigned to the msg, if msgid non-NULL
	msgtype	type of YControl message to send
	service_payload	val_value_t tree to add to message payload NULL if not used
	msg_status	NO_ERR or error status for message; ignored if service_payload is non-NULL

Returns: status

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ycontrol_send_error()

status_t ycontrol_send_error	(	const xmlChar *	service_id,
		uint32 *	msgid,
		status_t	msg_status,
		uint32	error_index,
		const xmlChar *	error_message,
		const xmlChar *	txid_str
	)

Send a YControl <error> message.

Parameters

service_id	service sending this message
msgid	address of message ID; for response this is non-zero
msg_status	NO_ERR or error status for message; ignored if service_payload is non-NULL
error_index	error index if sending an <error> response
error_message	error message if sending an <error> response
txid_str	transaction-id string to add (may be NULL to skip)

Returns: status

Here is the call graph for this function:

◆ ycontrol_send_ex()

status_t ycontrol_send_ex	(	const xmlChar *	service_id,
		uint32 *	msgid,
		ycontrol_msgtype_t	msgtype,
		val_value_t *	service_payload,
		status_t	msg_status,
		const xmlChar *	txid_str
	)

Send a YControl message (extended)

Parameters

	service_id	service sending this message
[out]	msgid	address of message ID; for response this is non-zero *msgid set to the message ID assigned to the msg, if msgid non-NULL
	msgtype	type of YControl message to send
	service_payload	val_value_t tree to add to message payload NULL if not used
	msg_status	NO_ERR or error status for message; ignored if service_payload is non-NULL
	txid_str	transaction-id string

Returns: status

Here is the call graph for this function:

◆ ycontrol_send_ex2()

status_t ycontrol_send_ex2	(	const xmlChar *	service_id,
		uint32 *	msgid,
		ycontrol_msgtype_t	msgtype,
		val_value_t *	service_payload,
		status_t	msg_status,
		boolean	with_origin,
		const xmlChar *	txid_str
	)

Send a YControl message (extended2)

Parameters

	service_id	service sending this message
[out]	msgid	address of message ID; for response this is non-zero *msgid set to the message ID assigned to the msg, if msgid non-NULL
	msgtype	type of YControl message to send
	service_payload	val_value_t tree to add to message payload NULL if not used
	msg_status	NO_ERR or error status for message; ignored if service_payload is non-NULL
	with_origin	TRUE to set origin attibutes (used for NMDA GET)
	txid_str	transaction-id string

Returns: status

Here is the call graph for this function:

◆ ycontrol_send_ok()

status_t ycontrol_send_ok	(	const xmlChar *	service_id,
		uint32 *	msgid,
		const xmlChar *	txid_str
	)

Send a YControl <ok> message.

Parameters

service_id	service sending this message
msgid	address of message ID; for response this is non-zero
txid_str	transaction-id string to add (may be NULL to skip)

Returns: status

Here is the call graph for this function:

◆ ycontrol_service_reconnect()

void ycontrol_service_reconnect ( void )

Start the main server reconnect for the registered services.

Called from internal message handler. Not a user API.

Here is the caller graph for this function:

◆ ycontrol_service_start()

void ycontrol_service_start ( void )

Start the registered services.

Called from internal message handler. Not a user API.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ycontrol_service_stop()

void ycontrol_service_stop ( void )

Stop the registered services.

Called from internal message handler. Not a user API.

Here is the call graph for this function:

◆ ycontrol_set_retry_interval()

void ycontrol_set_retry_interval ( int retry_int )

Set the re-connect retry interval.

Parameters

retry_int number of milliseconds to wait (5000 = 5 seconds)
must be >= 50

◆ ycontrol_set_retry_limit()

void ycontrol_set_retry_limit ( uint16 retry_limit )

Set the re-connect retry limit.

Parameters

retry_limit max number of connect attempts to make (1..max)

◆ ycontrol_set_server_root()

status_t ycontrol_set_server_root ( const char * server_root )

Set the server-root when running in Multi-Instance Mode.

MUST be before ycontrol_init2 API called
Needed in subsys connection setup to pick correct socket

Parameters

server_root server_root string to set

Returns: status

Here is the call graph for this function:

◆ ycontrol_set_timer_handler()

void ycontrol_set_timer_handler ( ycontrol_timer_handler_t timer_handler )

Set the timer callback handler.

Only 1 is allowed!!

This is an internal API used for reconnections.

Parameters

timer_handler timer callback to use; NULL to clear

Here is the caller graph for this function:

◆ ycontrol_setup_reconnect()

void ycontrol_setup_reconnect ( void )

Setup the YControl profile to reconnect after the retry interval with the incoming message from the server.

The server dropped the connection or crashed.

Here is the caller graph for this function:

◆ ycontrol_shutdown_now()

boolean ycontrol_shutdown_now ( void )

Check if the YControl subsystem has shut down because a <shutdown-event> was received from the server.

Returns: TRUE is YControl has shut down
FALSE if YControl has not shut down

Here is the caller graph for this function:

◆ ycontrol_shutdown_requested()

boolean ycontrol_shutdown_requested ( void )

Check if a control message handler shutdown is in progress.

Returns: TRUE if shutdown mode has been started

Here is the caller graph for this function:

◆ ycontrol_unregister_service()

void ycontrol_unregister_service ( const xmlChar * service_name )

Unregister a specific service.

Parameters

service_name service to unregister