diff --git a/reowolf.h b/reowolf.h index e57118b313d79158b18039f8591994cb5f88e780..d5d491feda2e55a058b56d62adf92463d73db0a5 100644 --- a/reowolf.h +++ b/reowolf.h @@ -12,11 +12,44 @@ typedef struct Connector Connector; typedef uint32_t ControllerId; +/** + * Provides a binding annotation for the port with the given index with "active": + * (The port will conenct to a "passive" port at the given address during connect()) + * Returns: + * - 0 for success + * - 1 if the port was already bound and was left unchanged + * # Safety + * TODO + */ +int connector_bind_active(Connector *connector, unsigned int proto_port_index, const char *address); + +/** + * Provides a binding annotation for the port with the given index with "native": + * (The port is exposed for reading and writing from the application) + * Returns: + * # Safety + * TODO + */ +int connector_bind_native(Connector *connector, uintptr_t proto_port_index); + +/** + * Provides a binding annotation for the port with the given index with "native": + * (The port is exposed for reading and writing from the application) + * Returns: + * # Safety + * TODO + */ +int connector_bind_passive(Connector *connector, + unsigned int proto_port_index, + const char *address); + /** * Configures the given Reowolf connector with a protocol description in PDL. * Returns: + * # Safety + * TODO */ -int connector_configure(Connector *connector, char *pdl); +int connector_configure(Connector *connector, char *pdl, char *main); /** * Provides a binding annotation for the port with the given index with "active": @@ -24,11 +57,15 @@ int connector_configure(Connector *connector, char *pdl); * Returns: * - 0 SUCCESS: connected successfully * - TODO error codes + * # Safety + * TODO */ int connector_connect(Connector *connector, uint64_t timeout_millis); /** * Destroys the given connector, freeing its underlying resources. + * # Safety + * TODO */ void connector_destroy(Connector *connector); @@ -37,73 +74,74 @@ void connector_destroy(Connector *connector); * Returns: * - 0 if an error was cleared * - 1 if there was no error to clear + * # Safety + * TODO */ int connector_error_clear(void); /** * Returns a pointer into the error buffer for reading as a null-terminated string * Returns null if there is no error in the buffer. + * # Safety + * TODO */ const char *connector_error_peek(void); /** - * Creates and returns Reowolf Connector structure allocated on the heap. + * Prepares to synchronously put a message at the given port, writing it to the given buffer. + * - 0 SUCCESS + * - 1 this port has the wrong direction + * - 2 this port is already marked to get + * # Safety + * TODO */ -Connector *connector_new(void); +int connector_get(Connector *connector, unsigned int proto_port_index); -int connector_next_batch(Connector *connector); - -int connector_sync(Connector *connector, uint64_t timeout_millis); +/** + * # Safety + * TODO + */ +int connector_gotten(Connector *connector, + unsigned int proto_port_index, + const unsigned char **buf_ptr_outptr, + unsigned int *len_outptr); /** * Creates and returns Reowolf Connector structure allocated on the heap. */ -Connector *connector_with_controller_id(ControllerId controller_id); +Connector *connector_new(void); /** - * Provides a binding annotation for the port with the given index with "active": - * (The port will conenct to a "passive" port at the given address during connect()) - * Returns: - * - 0 for success - * - 1 if the port was already bound and was left unchanged + * # Safety + * TODO */ -int port_bind_active(Connector *connector, unsigned int proto_port_index, const char *address); +int connector_next_batch(Connector *connector); /** - * Provides a binding annotation for the port with the given index with "native": - * (The port is exposed for reading and writing from the application) - * Returns: + * Prepares to synchronously put a message at the given port, reading it from the given buffer. + * # Safety + * TODO */ -int port_bind_native(Connector *connector, uintptr_t proto_port_index); +int connector_put(Connector *connector, + unsigned int proto_port_index, + unsigned char *buf_ptr, + unsigned int msg_len); /** - * Provides a binding annotation for the port with the given index with "native": - * (The port is exposed for reading and writing from the application) - * Returns: + * # Safety + * TODO */ -int port_bind_passive(Connector *connector, unsigned int proto_port_index, const char *address); - -int port_close(Connector *connector, unsigned int _proto_port_index); +int connector_sync(Connector *connector, uint64_t timeout_millis); /** - * Prepares to synchronously put a message at the given port, writing it to the given buffer. - * - 0 SUCCESS - * - 1 this port has the wrong direction - * - 2 this port is already marked to get + * Creates and returns Reowolf Connector structure allocated on the heap. */ -int port_get(Connector *connector, unsigned int proto_port_index); +Connector *connector_with_controller_id(ControllerId controller_id); /** - * Prepares to synchronously put a message at the given port, reading it from the given buffer. + * # Safety + * TODO */ -int port_put(Connector *connector, - unsigned int proto_port_index, - unsigned char *buf_ptr, - unsigned int msg_len); - -int read_gotten(Connector *connector, - unsigned int proto_port_index, - const unsigned char **buf_ptr_outptr, - unsigned int *len_outptr); +int port_close(Connector *connector, unsigned int _proto_port_index); #endif /* REOWOLF_HEADER_DEFINED */