yumapro  23.10T-6
YumaPro SDK
Loading...
Searching...
No Matches
Core Functions

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_tycontrol_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_cleanupTRUE 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
scbsession 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_namename 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
argcargument count
argvargument array
subsys_idsub-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_idserver ID to use in registration to main server
server_addrhost address of the main server to connect to
server_portTCP 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
tcbtcb 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
argcargument count
argvargument array
subsys_iddefault sub-system identifier if no –subsys-id CLI parm is found
is_standbytrue 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
argcargument count
argvargument array
subsys_iddefault sub-system identifier if no –subsys-id CLI parm is found
is_standbytrue if agt_yp_ha_standby is calling; this will cause ycontrol_signal to be skipped
quiet_modetrue: 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_nameunique name of the service
service_startservice start callback
service_stopservice stop callback
service_rcvrMessage receiver callback
service_shutservice 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_nameunique name of the service
service_startservice start callback
service_stopservice stop callback
service_rcvrMessage receiver callback
service_shutservice shutdown callback
service_reconnectservice 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_idservice sending this message
[out]msgidaddress of message ID; for response this is non-zero
*msgid set to the message ID assigned to the msg, if msgid non-NULL
msgtypetype of YControl message to send
service_payloadval_value_t tree to add to message payload
NULL if not used
msg_statusNO_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_idservice sending this message
msgidaddress of message ID; for response this is non-zero
msg_statusNO_ERR or error status for message; ignored if service_payload is non-NULL
error_indexerror index if sending an <error> response
error_messageerror message if sending an <error> response
txid_strtransaction-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_idservice sending this message
[out]msgidaddress of message ID; for response this is non-zero
*msgid set to the message ID assigned to the msg, if msgid non-NULL
msgtypetype of YControl message to send
service_payloadval_value_t tree to add to message payload
NULL if not used
msg_statusNO_ERR or error status for message; ignored if service_payload is non-NULL
txid_strtransaction-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_idservice sending this message
[out]msgidaddress of message ID; for response this is non-zero
*msgid set to the message ID assigned to the msg, if msgid non-NULL
msgtypetype of YControl message to send
service_payloadval_value_t tree to add to message payload
NULL if not used
msg_statusNO_ERR or error status for message; ignored if service_payload is non-NULL
with_originTRUE to set origin attibutes (used for NMDA GET)
txid_strtransaction-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_idservice sending this message
msgidaddress of message ID; for response this is non-zero
txid_strtransaction-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_intnumber 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_limitmax 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_rootserver_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_handlertimer 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_nameservice to unregister