yumapro  24.10-2
YumaPro SDK
Loading...
Searching...
No Matches

YControl protocol is used by services between the main server and subsystems. More...

Collaboration diagram for YControl:

Data Structures

struct  agt_ycontrol_cb_t
 control block for 1 registered service handler More...
 
struct  agt_ycontrol_subsys_t
 control block for connected 1 subsystem; used to send event messages to the subsystem More...
 

Macros

#define AGT_YCONTROL_MAX_SERVICES   4
 number of services hard-wired based on defined YumaPro features
 

Typedefs

typedef status_t(* agt_ycontrol_service_fn_t) (ses_cb_t *scb, ycontrol_msgtype_t msgtype, uint32 msgid, const xmlChar *subsys_id, ycontrol_msgbody_t msgbody_type, val_value_t *msgbody, boolean *scb_valid)
 Callback template for YControl services: message handler. More...
 
typedef void(* agt_ycontrol_subsys_gone_fn_t) (const xmlChar *subsys_id)
 brief Callback template for YControl services: subsys gone handler More...
 

Functions

status_t agt_ycontrol_init1 (void)
 Initialize the agt_ycontrol module (phase 1) More...
 
status_t agt_ycontrol_init2 (void)
 Initialize the agt_ycontrol module (phase 2) More...
 
void agt_ycontrol_cleanup (void)
 Cleanup the agt_ycontrol module. More...
 
boolean agt_ycontrol_dispatch (ses_cb_t *scb, xml_node_t *top)
 Handle an incoming <ycontrol> message from a subsystem. More...
 
status_t agt_ycontrol_send_payload (ses_cb_t *scb, const xmlChar *service_id, uint32 *msgid, ycontrol_msgtype_t msgtype, val_value_t *service_payload, boolean with_ywattrs)
 Send the subsystem <ycontrol> message to the sevice manager on the specified session, using the <payload> variant. More...
 
status_t agt_ycontrol_send_callback (ses_cb_t *scb, const xmlChar *service_id, uint32 *msgid, ycontrol_msgtype_t msgtype, boolean with_ywattrs, obj_template_t *service_obj, agt_rpc_data_cb_t data_cbfn, rpc_msg_t *rpcmsg, boolean need_filesave)
 Send the subsystem <ycontrol> message to the sevice manager on the specified session, using the <payload> variant. More...
 
status_t agt_ycontrol_send_error (ses_cb_t *scb, const xmlChar *service_id, uint32 msgid, status_t res, const xmlChar *errstr)
 Send a ycontrol error message. More...
 
status_t agt_ycontrol_send_ok (ses_cb_t *scb, const xmlChar *service_id, uint32 msgid)
 Send a ycontrol OK message. More...
 
status_t agt_ycontrol_send_event (const xmlChar *service_id, val_value_t *service_payload, boolean with_ywattrs)
 Send a server event to all the active subsystems. More...
 
status_t agt_ycontrol_send_event_subsys (const xmlChar *service_id, val_value_t *service_payload, boolean with_ywattrs, const xmlChar *subsys_id)
 Send a server event to a specific subsystem or all subsystems. More...
 
status_t agt_ycontrol_register_service (const xmlChar *service_name, agt_ycontrol_service_fn_t service_fn)
 Register a YControl service layer. More...
 
status_t agt_ycontrol_register_service_ex (const xmlChar *service_name, agt_ycontrol_service_fn_t service_fn, agt_ycontrol_subsys_gone_fn_t subsys_gone_fn)
 Register a YControl service layer (extended) More...
 
void agt_ycontrol_unregister_service (const xmlChar *service_name)
 un-register a callback for 1 YControl service type More...
 
status_t agt_ycontrol_add_subsys (ses_id_t subsys_sid, const xmlChar *subsys_id)
 Add a subsystem connection to the ycontrol manager. More...
 
void agt_ycontrol_remove_subsys (ses_id_t sid, const xmlChar *subsys_id)
 Remove a subsystem connection to the ycontrol manager because the connection was closed or shutting down. More...
 
obj_template_tagt_ycontrol_get_obj (void)
 Get the ycontrol container object. More...
 
ses_cb_tagt_ycontrol_get_scb (const xmlChar *subsys_id)
 Get the session control block for the specified subsys ID. More...
 
void agt_ycontrol_drop_session (ses_id_t sid)
 Notify the agt_ycontrol module that a YControl session has been closed and needs to be cleaned up. More...
 
boolean agt_ycontrol_any_subsys_active (void)
 Check if there are any subsystems active. More...
 
status_t agt_ycontrol_send_shutdown_event (void)
 Send a <shutdown-event> message to all subsystems. More...
 
status_t agt_ycontrol_send_shutdown_event_byservice (const xmlChar *service_id)
 Send a <shutdown-event> message to a specific subsystems. More...
 
boolean agt_ycontrol_init_was_done (void)
 Return TRUE if this module has been initialized. More...
 
const xmlChar * agt_ycontrol_get_subsys_id (ses_id_t sid)
 Get the subsystem-id for the session ID. More...
 

Detailed Description

YControl protocol is used by services between the main server and subsystems.

Each service registers a unique service name and provides a message receiver callback.

Typedef Documentation

◆ agt_ycontrol_service_fn_t

typedef status_t(* agt_ycontrol_service_fn_t) (ses_cb_t *scb, ycontrol_msgtype_t msgtype, uint32 msgid, const xmlChar *subsys_id, ycontrol_msgbody_t msgbody_type, val_value_t *msgbody, boolean *scb_valid)

Callback template for YControl services: message handler.

Parameters
scbsession control block for YControl session
msgtypemessage type
msgidmessage ID
subsys_idsubsystem identifier
msgbody_typetype of message body (OK, PAYLOAD, ERROR)
msgbodyval_value_t representing the message body the service-specific payload node(s) will be child nodes if this is the <payload> container
[out]scb_validaddress of return scb_valid flag
*scb_valid TRUE if scb pointer still valid; FALSE if not
Returns
status of the operation

◆ agt_ycontrol_subsys_gone_fn_t

typedef void(* agt_ycontrol_subsys_gone_fn_t) (const xmlChar *subsys_id)

brief Callback template for YControl services: subsys gone handler

Called by YControl when the subsystem has gone away

Parameters
subsys_idsubsystem identifier that is gone (dropped, crashed)

Function Documentation

◆ agt_ycontrol_add_subsys()

status_t agt_ycontrol_add_subsys ( ses_id_t  subsys_sid,
const xmlChar *  subsys_id 
)

Add a subsystem connection to the ycontrol manager.

Parameters
subsys_sidsession ID for subsystem connnection
subsys_idsubsystem ID
Returns
status of the operation
Here is the call graph for this function:
Here is the caller graph for this function:

◆ agt_ycontrol_any_subsys_active()

boolean agt_ycontrol_any_subsys_active ( void  )

Check if there are any subsystems active.

Returns
TRUE if any subsystems active

◆ agt_ycontrol_cleanup()

void agt_ycontrol_cleanup ( void  )

Cleanup the agt_ycontrol module.

Unregister the top-level <ycontrol> element

Here is the call graph for this function:

◆ agt_ycontrol_dispatch()

boolean agt_ycontrol_dispatch ( ses_cb_t scb,
xml_node_t top 
)

Handle an incoming <ycontrol> message from a subsystem.

Parameters
scbsession control block
toptop element descriptor
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:

◆ agt_ycontrol_drop_session()

void agt_ycontrol_drop_session ( ses_id_t  sid)

Notify the agt_ycontrol module that a YControl session has been closed and needs to be cleaned up.

Parameters
sidsession ID that was dropped
Here is the caller graph for this function:

◆ agt_ycontrol_get_obj()

obj_template_t * agt_ycontrol_get_obj ( void  )

Get the ycontrol container object.

Returns
pointer to ycontrol object
Here is the caller graph for this function:

◆ agt_ycontrol_get_scb()

ses_cb_t * agt_ycontrol_get_scb ( const xmlChar *  subsys_id)

Get the session control block for the specified subsys ID.

Parameters
subsys_idsubsystem identifier
Returns
pointer to session control block; NULL if not found
Here is the call graph for this function:
Here is the caller graph for this function:

◆ agt_ycontrol_get_subsys_id()

const xmlChar * agt_ycontrol_get_subsys_id ( ses_id_t  sid)

Get the subsystem-id for the session ID.

Parameters
sidsession identifier
Returns
pointer to subsystem identifier
Here is the caller graph for this function:

◆ agt_ycontrol_init1()

status_t agt_ycontrol_init1 ( void  )

Initialize the agt_ycontrol module (phase 1)

Initialize module variables and load yumaworks-ycontrol module

Returns
status
Here is the call graph for this function:
Here is the caller graph for this function:

◆ agt_ycontrol_init2()

status_t agt_ycontrol_init2 ( void  )

Initialize the agt_ycontrol module (phase 2)

Adds the agt_ycontrol_dispatch function as the handler for the NETCONF <ycontrol> top-level element.

Returns
NO_ERR if all okay, the minimum spare requests will be malloced

◆ agt_ycontrol_init_was_done()

boolean agt_ycontrol_init_was_done ( void  )

Return TRUE if this module has been initialized.

Returns
TRUE if innit1 and init2 done; FALSE if not
Here is the caller graph for this function:

◆ agt_ycontrol_register_service()

status_t agt_ycontrol_register_service ( const xmlChar *  service_name,
agt_ycontrol_service_fn_t  service_fn 
)

Register a YControl service layer.

Add message callback for 1 YControl service type

Parameters
service_nameYControl service name
service_fnservice message callback function
Returns
status of the operation
Here is the call graph for this function:
Here is the caller graph for this function:

◆ agt_ycontrol_register_service_ex()

status_t agt_ycontrol_register_service_ex ( const xmlChar *  service_name,
agt_ycontrol_service_fn_t  service_fn,
agt_ycontrol_subsys_gone_fn_t  subsys_gone_fn 
)

Register a YControl service layer (extended)

Add message callback and subsys_gone callback for 1 YControl service type

Parameters
service_nameYControl service name
service_fnservice message callback function
subsys_gone_fnsubsys dropped callback function (may be NULL)
Returns
status of the operation
Here is the call graph for this function:
Here is the caller graph for this function:

◆ agt_ycontrol_remove_subsys()

void agt_ycontrol_remove_subsys ( ses_id_t  sid,
const xmlChar *  subsys_id 
)

Remove a subsystem connection to the ycontrol manager because the connection was closed or shutting down.

Subsystems have associated control sessions. Need to use this SID to locate correct subsystem in case there are multiple subsystems with the same ID trying to establish connection with the server.

Parameters
sidsubsystem's associated SID
subsys_idsubsystem ID to remove
Here is the call graph for this function:
Here is the caller graph for this function:

◆ agt_ycontrol_send_callback()

status_t agt_ycontrol_send_callback ( ses_cb_t scb,
const xmlChar *  service_id,
uint32 *  msgid,
ycontrol_msgtype_t  msgtype,
boolean  with_ywattrs,
obj_template_t service_obj,
agt_rpc_data_cb_t  data_cbfn,
rpc_msg_t rpcmsg,
boolean  need_filesave 
)

Send the subsystem <ycontrol> message to the sevice manager on the specified session, using the <payload> variant.

The <payload> will be filled in by the callback function

Parameters
scbsession control block
service_idservice sending the message
[in,out]msgidaddress of message ID;
  • for response this is non-zero
  • *msgid set to the message ID assigned to the message. Only if *msgid was zero on input.
msgtypetype of YControl message to send; One of:
  • YCONTROL_MSG_SERVER_REQUEST
  • YCONTROL_MSG_SERVER_RESPONSE
  • YCONTROL_MSG_SERVER_EVENT
with_ywattrsTRUE to add attrs NS to msg hdr; FALSE if not
service_objobject template for the service layer
data_cbfnCallback function to inject data
rpcmsgRPC message holding the state for this data
need_filesave== save to file first flag
  • TRUE to save to file first because it is possible the subsys that requested the operation needs to be called for a SIL-SA function;
  • FALSE it is OK to call the data_cbfn while the return message is in progress; no need to save to disk first
Returns
status

◆ agt_ycontrol_send_error()

status_t agt_ycontrol_send_error ( ses_cb_t scb,
const xmlChar *  service_id,
uint32  msgid,
status_t  res,
const xmlChar *  errstr 
)

Send a ycontrol error message.

Parameters
scbsession control block
service_idservice_id from request
msgidmessage ID from request
resinternal status code
errstrerror message
Returns
status
Here is the call graph for this function:

◆ agt_ycontrol_send_event()

status_t agt_ycontrol_send_event ( const xmlChar *  service_id,
val_value_t service_payload,
boolean  with_ywattrs 
)

Send a server event to all the active subsystems.

Parameters
service_idservice sending the message
service_payloadval_value_t tree to add to message payload
NULL if not used
with_ywattrsTRUE to add attrs NS to msg hdr; FALSE if not
Returns
status
Here is the call graph for this function:
Here is the caller graph for this function:

◆ agt_ycontrol_send_event_subsys()

status_t agt_ycontrol_send_event_subsys ( const xmlChar *  service_id,
val_value_t service_payload,
boolean  with_ywattrs,
const xmlChar *  subsys_id 
)

Send a server event to a specific subsystem or all subsystems.

Parameters
service_idservice sending the message
service_payloadval_value_t tree to add to message payload
NULL if not used
with_ywattrsTRUE to add attrs NS to msg hdr; FALSE if not
subsys_idone subsystem to send event to or NULL if all subsystems that match
Returns
status
Here is the call graph for this function:
Here is the caller graph for this function:

◆ agt_ycontrol_send_ok()

status_t agt_ycontrol_send_ok ( ses_cb_t scb,
const xmlChar *  service_id,
uint32  msgid 
)

Send a ycontrol OK message.

Parameters
scbsession control block
service_idservice_id from request
msgidmessage ID from request
Returns
status
Here is the call graph for this function:

◆ agt_ycontrol_send_payload()

status_t agt_ycontrol_send_payload ( ses_cb_t scb,
const xmlChar *  service_id,
uint32 *  msgid,
ycontrol_msgtype_t  msgtype,
val_value_t service_payload,
boolean  with_ywattrs 
)

Send the subsystem <ycontrol> message to the sevice manager on the specified session, using the <payload> variant.

Parameters
scbsession control block
service_idservice sending the message
[in,out]msgidaddress of message ID;
  • for response this is non-zero
  • *msgid set to the message ID assigned to the message. Only if *msgid was zero on input.
msgtypetype of YControl message to send; One of:
  • YCONTROL_MSG_SERVER_REQUEST
  • YCONTROL_MSG_SERVER_RESPONSE
  • YCONTROL_MSG_SERVER_EVENT
service_payloadval_value_t tree to add to message payload
with_ywattrsTRUE to add attrs NS to msg hdr; FALSE if not
Returns
status
Here is the call graph for this function:
Here is the caller graph for this function:

◆ agt_ycontrol_send_shutdown_event()

status_t agt_ycontrol_send_shutdown_event ( void  )

Send a <shutdown-event> message to all subsystems.

Returns
status of the operation
Here is the call graph for this function:
Here is the caller graph for this function:

◆ agt_ycontrol_send_shutdown_event_byservice()

status_t agt_ycontrol_send_shutdown_event_byservice ( const xmlChar *  service_id)

Send a <shutdown-event> message to a specific subsystems.

Parameters
service_idservice sending the message
Returns
status of the operation
Here is the call graph for this function:

◆ agt_ycontrol_unregister_service()

void agt_ycontrol_unregister_service ( const xmlChar *  service_name)

un-register a callback for 1 YControl service type

Parameters
service_nameYControl service name
Here is the call graph for this function:
Here is the caller graph for this function: