YControl Subsystem
A subsystem application consists of a YControl subsystem and one or more upper-layer services. Only the SIL-SA Subsystem and DB-API Subsystem are supported at this time.
The YControl subsystem is used to allow asynchronous operation between netconfd-pro and higher layer services. The YControl subsystem is a shared library that is linked with other libraries and runs in the subsystem application 'vendor' process.
The YControl subsystem is designed to support multiple independent upper-layer services . The main server does not provide API support for custom service layers at this time.
Note
The YControl library supports only one subsystem at a time.
A subsystem can support one 'sil-sa' service and/or one 'db-api' service.
Only one subsystem can be registered with the server.
E.g., subsys-id
subsys1
andsubsys2
cannot both use the same subsystem application.
Multiple subsystem applications must be used instead.
E.g., --subsys-id=
subsys1
is used in one application and --subsys-id=subsys2
is used in a separate application.
An IO poll API is called periodically by the vendor process to check for incoming messages.
The subsystem provides a communication service between the server and another process. It does not provide any high-level service within the server. It handles the following services:
connection and reconnection to the netconfd-pro server
configurable connect and retry parameters
the server can boot before or after the process using YControl.
registration API for higher layer services
message processing API for higher layer services
Subsystem Software Components
Server to Subsystem Service Layer
YControl API Functions
Each high level service must register the proper callback functions with the YControl subsystem.
The application will poll the IO function periodically to handle communication with the main server. The callback functions registers with the subsystem will be invoked as needed, based on the received message.
The main YControl functions are described in this section.
The following sample applications show how to use YControl API functions.
combo-app
db-api-app
sil-sa-app
py-sil-app
Initialization and Cleanup
The following functions are used for initialization and cleanup of the YControl subsystem:
ycontrol_init: Phase 1 Initialization
ycontrol_init2: Phase 2 Initialization
ycontrol_register_service: Register a set of callback functions fort a high-level service
ycontrol_cleanup: Shutdown YControl subsystem and all upper layer services
ycontrol_request_shutdown: Trigger shutdown of YControl subsystem and all upper layer services
ycontrol_shutdown_requested: Check if shutdown of YControl subsystem has been triggered
-
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
-
status_t ycontrol_init2(void)
Phase 2 initialization.
Setup connection to server.
- Returns:
status
-
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
-
void ycontrol_cleanup(void)
Cleanup ycontrol layer.
Called by the application to cleanup resources. Must call if ycontrol_init function variant called.
-
void ycontrol_request_shutdown(void)
Request a control message handler shutdown.
This is the correct way to shutdown YControl from the application.
-
boolean ycontrol_shutdown_requested(void)
Check if a control message handler shutdown is in progress.
- Returns:
TRUE if shutdown mode has been started
Runtime Functions
The following functions are used after initialization is complete to access the YControl subsystem:
ycontrol_check_io: Check for any incoming messages from the main server
ycontrol_is_ready: Make sure the YControl subsystem is ready for a new request
ycontrol_send: Send any YControl message to the main server
ycontrol_send_error: Send an error response to the main server
-
status_t ycontrol_check_io(void)
Check for input/output.
Called from application to process any incoming YControl messages.
- Returns:
status
-
boolean ycontrol_is_ready(void)
Check if the ycontrol ready is up and ready to be used.
- Returns:
TRUE if ready; FALSE if not
-
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
msgid -- [out]
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
-
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
YControl Message Structure
There are 6 types of messages supported, indicated by the message-type leaf
server-request: request from server to subsystem, expecting a subsys-response
server-response: response from server to subsystem to a subsys-request message
server-event: event from server to subsystem; no response
subsys-request: request from subsystem to server, expecting a server-response
subsys-response: response from subsystem to server to a server-request message
subsys-event: event from subsystem to server; no response
Each message type shares the same payload structure. There are 3 formats, specified by the 'message-payload' choice-stmt in the YANG module.'
container payload: message body
leaf ok: NO_ERR response
container error: error response
The yumaworks-ycontrol.yang module contains the YControl message structure.