Libnjaim provides 14 functions as programming interface.
int start_core(char *name, char *servip, u_int16_t servport);
Function: initialization and login Parameter: name, login name servip, server IP servport, server port Return: 1, ok 0, error
void finish_core();
Function: finalization and logout Parameter: none Return: none
int register_type(char *type);
Function: register a message type Parameter: type, type to be registered Return: 1, ok 0, error
When libnjaim receives a message of registered type, it will acknowledge the message and pass the message to user.
int unregister_type(char *type);
Function: unregister a message type Parameter: type, type to be unregistered Return: 1, ok 0, error
int is_registered(char *type);
Function: check whether a type is registered Parameter: type, type to be searched Return: 1, registered 0, unregistered
int send_message(char *type, char *name, char *text, int nsec, char *res);
Function: send message to server and wait for reply Parameter: type, type of the message name, peer name text, text of the message nsec, number of seconds to wait res, buffer to store server reply Return: 1, ok 0, timed out -1, error
int sendmsg_reg(char *type, char *name, char *text, u_int32_t sid, int nsec, char *res);
Function: send registered message to peer and wait for acknowledgement Parameter: type, type of the message name, peer name text, text of the message sid, session id nsec, number of seconds to wait res, buffer to store peer acknowledgement Return: 1, ok 0, timed out -1, error
The session id will be used in uniconnect and uniaccept.
int recvmsg_reg(char *res);
Function: receive registered message Parameter: res, buffer to store message Return: 1, ok 0, error
When one side calls sendmsg_reg to send a registered message, the other side should call recvmsg_reg to receive the message.
unisocket_t *uniconnect(char *name, u_int32_t sid);
Function: connect peer by name universally Parameter: name, peer name sid, session id Return: !NULL, connected unisocket NULL, error
After calling start_core successfully, you can connect another client by his login name (the other side should call uniaccept at about the same time), as well as specifying a unique session id (the same with the session id of the other side's uniaccept call), to prevent mistakes in multi-threading.
unisocket_t *uniaccept(char *name, u_int32_t sid);
Function: accept peer by name universally Parameter: name, peer name sid, session id Return: !NULL, connected unisocket NULL, error
After calling start_core successfully, you can accept another client by his login name (the other side should call uniconnect at about the same time, as well as specifying a unique session id (the same with the session id of the other side's uniconnect call), to prevent mistakes in multi-threading.
ssize_t unirecv(unisocket_t *us, void *buf, size_t len, int flags);
Function: receive bytes from unisocket Parameter: us, connected unisocket buf, buffer address len, buffer length flags, flags for syscall recv Return: >0, number of bytes received 0, peer close connection -1, error
After calling uniconnect or uniaccept successfully, you can read and write the unisocket just like any normal TCP socket.
ssize_t unisend(unisocket_t *us, void *buf, size_t len, int flags);
Function: send bytes to unisocket Parameter: us, connected unisocket buf, buffer address len, buffer length flags, flags for syscall send Return: >0, number of bytes sent 0, nothing was sent -1, error
int unishutdown(unisocket_t *us, int how);
Function: half close connection Parameter: us, connected unisocket how, direction to close Return: 0, ok -1, error
int uniclose(unisocket_t *us);
Function: close connection Parameter: us, connected unisocket Return: 0, ok -1, error
When you are finished with the unisocket, close it.
Here is a common scenario (some steps are omitted, please refer to test.c) :
Alice sends : "TYPE=CUSTOM NAME=Bob TEXT=1234" (TEXT field is session id).
Bob receives : "TYPE=CUSTOM NAME=Alice/4.3.2.1:5 TEXT=1234".
Bob calls uniaccept("Alice", 1234).
Alice calls uniconnect("Bob", 1234).
When both sides return ok, transfer data using unirecv and unisend.
The two close the connection by calling uniclose.