Obsolete
/
libipc-old
Archived
3
0
Fork 0
This repository has been archived on 2024-06-18. You can view files and clone it, but cannot push or open issues/pull-requests.
libipc-old/man/communication.h.3

112 lines
4.0 KiB
Groff
Raw Normal View History

2016-12-20 21:46:39 +01:00
.TH COMMUNICATION.H 3 2016-12-20 "" "Linux Programmer's Manual"
.SH NAME
communication.h \- all functions explained
.SH SYNOPSIS
.nf
.B #include <communication.h>
.sp
2018-10-04 00:30:47 +02:00
.BI "int ipc_server_init (int "argc ", char **" argv ", char **" env ", struct ipc_service *" srv "
2016-12-25 22:10:01 +01:00
.BI " , const char *" service_name );
2018-10-04 00:30:47 +02:00
.BI "int ipc_server_accept (struct ipc_service *" srv ", struct ipc_client *" p );
2016-12-20 21:46:39 +01:00
.sp
2018-10-04 00:30:47 +02:00
.BI "int ipc_server_read (const struct ipc_client *" p ", struct ipc_message *" message );
.BI "int ipc_server_write (const struct ipc_client *" p ", const struct ipc_message *" message );
2016-12-20 21:46:39 +01:00
.sp
2018-10-04 00:30:47 +02:00
.BI "int ipc_server_close (struct ipc_service *" srv );
2018-10-04 01:54:12 +02:00
.BI "int ipc_server_close_client (struct ipc_client *" p );
.BI "int ipc_server_select (struct ipc_clients *" fds ", struct ipc_service *" srv ", struct ipc_clients *" readfds );
2016-12-20 21:46:39 +01:00
2018-10-04 00:30:47 +02:00
.BI "int ipc_application_connection (int " argc ", char **" argv ", char **" env ", struct ipc_service *" srv
2016-12-25 22:10:01 +01:00
.BI " , const char *" service_name "
.BI " , const char *" connection_buffer ", size_t " bufsize );
2016-12-20 21:46:39 +01:00
.sp
2018-10-04 00:30:47 +02:00
.BI "int ipc_application_read (const struct ipc_service *" srv ", struct ipc_message *" message );
.BI "int ipc_application_write (const struct ipc_service *" srv ", const struct ipc_message *" message );
2016-12-20 21:46:39 +01:00
.sp
2018-10-04 00:30:47 +02:00
.BI "int ipc_application_close (struct ipc_service *" srv );
2016-12-20 21:46:39 +01:00
.fi
.SH DESCRIPTION
The
2018-10-03 21:52:11 +02:00
.BR ipc_server_init ()
2016-12-20 21:46:39 +01:00
function let the service declare itself, create a new unix socket and listen.
.I argc
,
2016-12-25 22:10:01 +01:00
.IR *argv
2016-12-20 21:46:39 +01:00
and
2016-12-25 22:10:01 +01:00
.IR *env
should be passed to the function in order to automatically change the behavior of the program without the application being modified.
2016-12-20 21:46:39 +01:00
.I *srv
2018-10-04 00:30:47 +02:00
is the pointer to the \fBstruct ipc_service\fR that should be filled (index and version parameters).
2018-10-03 21:24:20 +02:00
The \fBserver_init()\fR function will fill the rest of the elements of this structure, such as the unix socket path and the unix socket file descriptor in order to be able to receive new connections.
2016-12-20 21:46:39 +01:00
.PP
The
2018-10-03 21:52:11 +02:00
.BR ipc_server_accept ()
2016-12-20 21:46:39 +01:00
function accepts new connections.
.IR p
2018-10-04 01:22:50 +02:00
parameter is the client client that will be provided after the connection.
2016-12-25 22:10:01 +01:00
.PP
The
2018-10-03 21:52:11 +02:00
.BR ipc_server_read ()
2016-12-25 22:10:01 +01:00
and
2018-10-03 21:52:11 +02:00
.BR ipc_server_write ()
2018-10-04 01:22:50 +02:00
functions take respectively a message to read from, and a message to write to a client.
2016-12-25 22:10:01 +01:00
.PP
The
2018-10-04 01:54:12 +02:00
.BR ipc_server_close_client ()
2016-12-25 22:10:01 +01:00
and
2018-10-03 21:52:11 +02:00
.BR ipc_server_close ()
2018-10-04 01:22:50 +02:00
functions terminate respectively a client (closing its unix socket) and the service (closing and removing its named unix socket).
2016-12-25 22:10:01 +01:00
.PP
The
2018-10-03 21:52:11 +02:00
.BR ipc_server_select ()
2016-12-25 22:10:01 +01:00
takes three arguments,
.IR *ap
2018-10-04 01:22:50 +02:00
an array of clientes you want to listen on,
2016-12-25 22:10:01 +01:00
.IR *srv
the service which receives new connections and
.IR *ap_read
2018-10-04 01:22:50 +02:00
an array of clientes which have sent a message we need to read.
2016-12-25 22:10:01 +01:00
.PP
The
2018-10-03 21:52:11 +02:00
.BR ipc_application_connection ()
2016-12-25 22:10:01 +01:00
function takes
.I argc
,
.IR *argv
and
.IR *env
in argument for latter use.
It takes
.IR *srv
2018-10-04 00:30:47 +02:00
the pointer to the \fBstruct ipc_service\fR that should be filled (index and version parameters) and
2016-12-25 22:10:01 +01:00
will fill the rest of the elements of this structure, such as the unix socket path and the unix socket file descriptor of the service in order to be able to talk to it.
The function also takes
.IR *service_name
to deduce the pipe's name of the service.
Finally, the function takes
.IR *connection_buffer
and
.IR bufsize
arguments to send a buffer in the first message value for the connection, which is useful when the service needs configuration.
The function finally connects itself to the service.
\fBIn a near future, this function will be completed to invoke transparently the remote service\fR.
.PP
The
2018-10-03 21:52:11 +02:00
.BR ipc_application_read ()
2016-12-25 22:10:01 +01:00
and
2018-10-03 21:52:11 +02:00
.BR ipc_application_write ()
2016-12-25 22:10:01 +01:00
functions take respectively a message to read from, and a message to write to the service.
.PP
The
2018-10-03 21:52:11 +02:00
.BR ipc_application_close ()
2016-12-25 22:10:01 +01:00
function finally ends the communication to the service.
2016-12-20 21:46:39 +01:00
.SH RETURN VALUE
2016-12-25 22:10:01 +01:00
Most of the functions return an integer less than zero if there is an error.
.PP
For
2018-10-03 21:52:11 +02:00
.BR ipc_server_select()
2018-10-04 01:22:50 +02:00
if there is a new connection, the function will return \fBCONNECTION\fR, if there is one or more clientes talking the function will return \fBAPPLICATION\fR and finally if there are both a new connection and a client talking the function will return \fBCON_APP\fR.