Command Interface

Relevant source files

The following files were used as context for generating this wiki page:

• src/cmdif.h
• src/relp.c
• src/relpsess.c
• doc/relp.html
• src/scsyslog.c
• src/scrsp.c
• src/copen.c
• src/cserverclose.c

The Command Interface in librelp defines the mechanism by which the RELP engine dispatches and handles protocol-specific operations. It establishes a consistent interface between the core RELP engine and various command handlers, ensuring modularity and extensibility for both standard protocol commands and extensions like syslog message transfer.

Sources: src/cmdif.h:1-12, src/relp.c:1164-1172

Architecture and Dispatch Logic

The RELP engine utilizes a centralized dispatch function, relpEngineDispatchFrame, to route incoming RELP frames to their respective command handlers based on the command string contained in the frame header.

Frame Dispatch Flow

When a frame is received, the engine inspects the pFrame->cmd field and compares it against known command strings. If a match is found, the engine invokes the corresponding handler function. If the command is unknown, the engine responds with an error code.

The diagram shows the logical flow of frame dispatching from the central engine to specific handlers.
Sources: src/relp.c:1174-1215

Command Handler Definition

Command handlers are defined using standardized macros to ensure consistency across the library. These macros hide implementation details regarding object assertions and function entry/exit logic.

Macro	Description
PROTOTYPEcommand(type, cmd)	Defines the prototype for a command handler.
BEGINcommand(type, cmd)	Starts the implementation of a command handler, including object assertions for the frame and session.
ENDcommand	Finalizes the command handler function and handles function exit.

Sources: src/cmdif.h:55-68

Protocol Command Types

Commands in RELP are categorized as either regular commands (requiring a response) or hint commands (unacknowledged).

Regular Commands

Regular commands are issued by the client and must be acknowledged by the server with a rsp command. They use a transaction number (TXNR) of 1 or higher.

1. open: Establishes a connection and negotiates protocol versions and features (offers).
2. syslog: Used to transmit syslog messages.
3. close: Initiates a graceful session termination.

Hint Commands

Hints are unacknowledged messages that can be issued by both peers, typically using a TXNR of 0.

1. serverclose: Sent by a server to advise a client that the connection is closing, allowing the client to clean up resources quickly.

Sources: doc/relp.html:105-135, src/cserverclose.c:48-56

Command Execution Flow

The interaction between a client issuing a command and a server responding is a structured transaction.

The sequence diagram illustrates a standard synchronous command-response transaction.
Sources: doc/relp.html:150-165, src/scsyslog.c:48-77

Server-Side "syslog" Handler

The server-side syslog handler verifies if the command is enabled for the current session. If enabled, it invokes the configured application-level callbacks (onSyslogRcv, onSyslogRcv2, or onSyslogRcv3) to process the message data before sending a "200 OK" response.

Sources: src/scsyslog.c:48-80

Client-Side "rsp" Handler

The rsp handler parses the response header to extract the status code (e.g., 200) and human-readable message. It matches the response TXNR against unacknowledged frames in the session's queue to complete the transaction.

Sources: src/scrsp.c:85-115

Feature Negotiation (Offers)

During the open command execution, peers exchange "offers" to negotiate supported features.

Supported Offer	Description
relp_version	Specifies the protocol version (currently 1).
commands	Lists optional commands supported by the peer (e.g., syslog).
relp_software	Provides software name, version, and URL for troubleshooting.

Sources: doc/relp.html:138-163, src/copen.c:57-80

Conclusion

The Command Interface provides the structural backbone for the RELP protocol's reliability. By enforcing a strict command-response model via a unified dispatching mechanism, librelp ensures that every application-level event is acknowledged and that session states remain synchronized between peers.