commit 88e0d385d012eddff7c09a53854190ec1a3d7f75
parent 8607879cd7cd34e9daea9d670529b7a5ca358cad
Author: Dominik Schmidt <dominik@schm1dt.ch>
Date: Wed, 16 Oct 2019 10:07:03 +0200
Improve the man page
It now better adheres to the standard set in man-pages(7), and is generally
easier to understand (hopefully)
Diffstat:
| M | siproc.1 | | | 99 | +++++++++++++++++++++++++++++++++++++++++++++++++++---------------------------- |
1 file changed, 64 insertions(+), 35 deletions(-)
diff --git a/siproc.1 b/siproc.1
@@ -1,32 +1,57 @@
-.TH siproc 1 "2019-08-31" "0.0.1" "siproc man page"
+.TH siproc 1 "2019-10-16" "0.0.1" "siproc man page"
+.
.SH NAME
siproc \- a SIP softphone spawning processes for calls
+.
.SH SYNOPSIS
.SY
siproc
.I /path/to/executable
.RI [ args \&...]
.YS
+.
.SH DESCRIPTION
-siproc is a SIP client, that spawns the given process
+siproc is a SIP client, that spawns the process given by
.I /path/to/executable
for every incoming or outgoing call, passing it the command line parameters
.IR args .
-Using standard input and output, these processes can interact with the peer and do tasks
-like answering calls, playing files and many more.
+.PP
+Using standard input and output, these processes can exchange commands and events
+with the parent process, that allow interaction with the caller/callee.
+These command allow the program to answering calls, play files, send and receive
+DTMF Tones et cetera.
+On remote hangup, the child process is killed via SIGTERM.
+.
+.PP
The account settings and other configuration are read via environment variables.
-.SS MAIN PROGRAM COMMANDS
-The main program reads some commands on stdin, terminated by newlines:
+.
+.SH EXIT STATUS
+.IP 0
+on normal termination
+.IP 1
+on program or configuration error (check standard error for details)
+.SH ENVIRONMENT
+Configuration parameters are given via environment variables
.TP
-.B QUIT
-Terminates the program, disconnecting all calls.
+.B SIPROC_REGISTRAR_URI
+The server siproc should connect to, as a SIP URI (e.g "sip:myserver.tld")
.TP
-.B CALL [SIP URI]
-Call a number, with
-.B SIP URI
-the address to be called, e.g. sip:contact@remote.tld
+.B SIPROC_ID_URI
+The ID URI of the account used, e.g. "Full Name <sip:Account@myserver.lan>"
+.TP
+.B SIPROC_USERNAME
+The username of the account
+.TP
+.B SIPROC_USERNAME
+The password of the account
+.TP
+.B SIPROC_TRANSPORT_PORT
+The port used by siproc. This variable is optional, and defaults to 5060.
+If you want to run multiple instances of siproc on the same machine, set
+it to distinct values, since the softphone binds to it.
+.
.SS SUBPROCESS ENVIRONMENT VARIABLES
-The processes invoked by siproc are passed various environment variables:
+The processes spawned by siproc are passed the following environment variables:
.TP
.B SIPROC_REMOTE_URI
The SIP URI of the remote end
@@ -40,9 +65,26 @@ Some pjsip interna, look it up in their documentation of the struct CallInfo
.B SIPROC_OUTGOING
Whether the call being handled by this process is an incoming call (="n") or an
outgoing call (="y")
+.
+.SH PROCESS COMMANDS AND EVENTS
+This section will explain the communication protocol between the main process and
+its children, as well as the commands the main process can be given on its standard
+input.
+.
+.SS MAIN PROGRAM COMMANDS
+The main program reads some commands on standard input, terminated by newlines ('\\n'):
+.TP
+.B QUIT
+Terminates the program, disconnecting all calls.
+.TP
+.B CALL [SIP URI]
+Call a number, with
+.B SIP URI
+the address to be called, e.g. sip:contact@remote.tld
+.
.SS SUBPROCESS COMMANDS
-The process can then give commands via stdout and read events via stdin.
-Each command or event is separated by a newline ('\n').
+The spawned child process can give commands via stdout and read events via stdin.
+Each command or event is separated by a newline ('\\n').
The following commands are supported:
.TP
.B RINGING
@@ -72,7 +114,9 @@ Stop the file that has been added last.
Send a SIP message to the remote side
.TP
.B RECORD [FILE]
-Record the conversation to the given file. If no file is given, the current recording is stopped.
+Record the conversation to the given file. If no file is given, the current
+recording is stopped.
+.
.SS SUBPROCESS EVENTS
The following events can be read on stdin:
.TP
@@ -90,29 +134,14 @@ command
.TP
.B MESSAGE [STRING]
The given message has been received.
+.
.SS CALL TERMINATION
When the remote end hangs up, or the call is terminated in any other manner,
-the process is killed via SIGTERM, so a program can catch that signal for cleaning up.
-.SH ENVIRONMENT
-Configuration parameters are given via environment variables
-.TP
-.B SIPROC_REGISTRAR_URI
-The server siproc should connect to, as a SIP URI (e.g "sip:myserver.tld")
-.TP
-.B SIPROC_ID_URI
-The ID URI of the account used, e.g. "Full Name <sip:Account@myserver.lan>"
-.TP
-.B SIPROC_USERNAME
-The username of the account
-.TP
-.B SIPROC_USERNAME
-The password of the account
-.TP
-.B SIPROC_TRANSPORT_PORT
-The port used by siproc. This variable is optional, and defaults to 5060.
-If you want to run multiple instances of siproc on the same machine, set it to different values.
+the process is killed via SIGTERM. the child may catch that signal for clean up.
+.
.SH BUGS
Call forwarding does not seem to work
+.
.SH AUTHOR
Dominik Schmidt (dominik@schm1dt.ch)
