divertctrl - set/query ISDN diversion services for (E)DSS1
protocol
SYNOPSIS
divertctrl [wait] command driverid ...
DESCRIPTION
divertctrl is used to de/activate call diversions and
query actual activated diversion rules. The i4l diversion
services only work using the (E)DSS1 D-channel protocol in
conjunction with the HiSax passive card driver. For using
the services the global isdn drivers need to be compiled
with support for the diversion services. Additionally the
dss1_divert module has to be loaded. This module doesn't
require nor support any parameters at load time. After
successfully loading the module an entry
/proc/net/isdn/divert should appear in the filesystem.
When called without any parameters the divertctrl program
outputs a short help screen. Otherwise the first parameter
needs to be a command followed by a valid driver id. The
command may be preceeded by the optional wait keyword
specifying the program to wait until the desired command
could be completed or failed returning the result via the
exitcode. Otherwise the programm immediately returns after
invoking the desired action which may not be completed at
this moment.
For some commands the value "-" may be used as a valid
driver id specifying all available drivers. The driver id
is equivalent to the id parameter specified when loading
the HiSax driver for a particular card. All further
parameters are command dependant. The divertctrl program
may only be used with root access for security reasons.
The diversion services for i4l may be used in two indepen
dant ways:
1. Static call diversion
First possibility to handle diversions of incoming calls
is to use static diversion provided inside the providers
exchange. A static diversion once activated inside the
providers exchange requires no interaction with i4l. The
machine may even be shut down, but the diversion keeps
active until it is explicitely deactivated. The divertc
trl tool allows to set/reset and query such static rules
if the service is supported and has been subscribed at the
providers side. This services are only available in some
countries like germany. In other countries (like the
netherlands) keypad control is used to de/activate such
static rules. Static rules may be set/reset and queried
independantly by MSN (multiple subscriber number), basic
service (telephony, digital data, ..) and diversion proce
dure. Three diversion procedures are defined in the ETSI
CFU (call forward unconditional) is a procedure diverting
all incoming calls unconditionally for the programmed MSN
and basic service. The call will never be announced at
your side until CFU is deactivated again.
CFNR (call forward not reachable) is a procedure diverting
all incoming calls for the programmed MSN and basic ser
vice after locally signalling and waiting a certain time
out period. If the call is not answered during this time
out period it will be diverted to the new destination. The
timeout period is fixed in the providers exchange and is
normally 3 rings (about 12 to 15 seconds).
CFB (call forward busy) is a procedure diverting all
incoming calls for the programmed MSN and basic service
when all local resources taking the call are exhausted and
busy.
Commands for handling static call diversions
activate driverid <cfu,cfnr,cfb> msn service destination
Activate a static diversion for the given driver, msn and
service diverting the call to the specified destination.
All parameters need to be supplied, no wildcards are
allowed. Only one of the three diversion procedures cfu,
cfnr, cfb must be supplied. The value for the service may
be taken from the table of numeric codes of basic ser
vices. The value 0 specifies all available/subscribed ser
vices.
deactivate driverid <cfu,cfnr,cfb> msn service
Deactivate a static diversion for the given driver, msn
and service. All parameters need to be supplied, no wild
cards are allowed. Only one of the three diversion proce
dures cfu, cfnr, cfb must be supplied. The value for the
service may be taken from the table of numeric codes of
basic services. The value 0 specifies all available/sub
scribed services.
interrogate driverid <cfu,cfnr,cfb> [msn] [service]
Query static diversions for the given driver, msn and ser
vice. Only one of the three diversion procedures cfu,
cfnr, cfb must be supplied. The msn and service parameters
are optional. The value for the service may be taken from
the table of numeric codes of basic services. The value 0
specifies all available/subscribed services. If msn
and/or service parameters are not specified all matching
diversions are reported via stdout. But it is advisable
always to specify all parameters to keep the list as short
return diversion lists longer than 256 bytes. In this case
an empty response is generated by the exchange even if
there are diversions active !
2. Dynamic call diversion
Additionally the i4l diversion services offer a more flex
ible possibility to control call forwarding. Using the
dynamic call diversion the user has the possibilty to
specify rules for call forwarding by additional criterias.
The reaction to an incoming call may be dependant of MSN,
basic service, caller id, local subaddress, caller subad
dress and local resource (busy) state. The parameters may
be specified with wildcards, so that call criterias may be
grouped to match. Additionally the diversion actions may
be supplied with a precise timeout value which is not
dependant on any providers defaults. In order to work, the
supplumentary service CD (call deflection) has to be
available and subscribed at the providers exchange. The
dynamic diversion services are fully handled inside your
machine, so it must be powered up and activated for the
required purpose. After a successfull dynamic diversion
(so called deflection) no local line resources are
required. The lines are free for further incoming calls.
Dynamic Call deflection is controlled by a rule chain the
user has to supply using the divertctrl program. When an
incoming call arrives, calling data is compared against
the rules in the chain. If an incoming call matches a
rule, this rule is taken to execute the desired action.
All following rules are ignored. If there is no rule
match the diversion services simply ignore the call.
Commands for handling dynamic call diversions
flushrules [driverid]
Flushes (deletes) all rules for the selected driver. If no
driverid is given or it is specified as wilcard - all
rules for all drivers are removed. It is advisable to
call this command first when a complete new ruleset is to
be generated, to avoid conflicts with previous set rules.
appendrule driverid action msn si1 si2 callerid screen
delay option destnumber
This command appends a single rule at the end of the
existing rule chain. If the call arrives through the
desired driver, addresses the selected msn, si1, si2 and
matches the desired callerid and option the specified
action is executed. A value of - may be specified for the
driverid to match the rule for all available drivers. The
msn may be specified with a trailing - wildcard. for
123, but specifying 123- matches all msn starting with 123
followed by any digits or subaddresses which will not ver
ified. If only - is specified the rule matches all msn and
subaddresses. If your isdn line supports subaddressing it
is advisable to terminate all msn values with a - because
the msn check includes a possibly available subadress
which then may be reported as 123.456 for msn 123 with
subaddresses 456 for example. Subaddressing is a special
DSS1 feature not available in most countries and normally
needs to be specially subscribed. So most people need not
to think about it. The value of si1 represents the
numeric code of the desired and checked basic service for
the incoming call. This value may be selected from the
table below or just the value 0 specified for all services
to match. The value of si2 represents an additional ser
vice indicator for high layer compatibilty and is only
included for completeness. Just set it to 0 at the moment.
The callerid must match the number of the caller including
the subaddress if available. Again the special wildcard -
may be used to match specific groups of numbers. Addi
tionally a simple value of 0 may be specified. In this
case the rule will match only calls coming in without a
caller indentification. This will be the case if the
caller originates from a network not supporting callerids
or the caller suppressed the identification. The option
parameter may take the values 0 to 2 and specifies whether
the rule applies only during special local busy states.
The value of 0 lets the rule be valid during any local
busy state. A value of 1 lets the rule only apply to
incoming calls if the call is in a non waiting state. A
value of 2 applies te rule only to such calls which arrive
as waiting. This is normally the case when all local
resources (B-channels) are already in use. If the rule
criterias mentioned before match the incoming call, no
following rules will be checked and the desired action
will be executed. The value for the parameter action is
numeric and may take the values 0 to 4 at the moment. A
value of 0 lets the call to be ignored. The call will not
be reported through the ascii interface and not checked
against any following rules. A value of 1 will report the
call through the ascii interface but no other action will
take place. If the value 2 is specified the call will be
reported through the ascii interface and actively put in a
local proceeding state. This means that the providers
exchange is told, that your side needs more time to check
whether the call may be handled and in which way this will
be done. This value only is intended for use with local
or remote client software watching the ascii interface and
deciding what to do. No ringing signal is send to the
caller until the decision has been made or a timeout (typ
ically 5 to 15 seconds) occurs. An example would be a
software which announces the call to a user and requests
the desired action. At the moment a client software is
may only be intersting for programmers which want to write
their own client. If value of 4 is specified the call
will be actively rejected. The values from 0-2 and 4
don't require a destination number to be specified, as the
incoming call will not be deflected in this cases. The
last, but most interesting value for most people will be
the value 3. Specifying it, will let the call to be
deflected/diverted actively. For this reason additional
parameters are taken for interpretation. First of all
destnumber specifies the final number the call should be
diverted to. The parameter delay specifies after how many
seconds the call will be diverted towards the new destina
tion. A value of 0 deflects the call immediately like the
cfu in static diversons, any other value first announces
the caller a ringing state until the time is elapsed and
then the call will be diverted like in static cfnr. Dur
ing the ringing phase every other device on your line may
pick up the call of course. The value of the parameter
screen may take the values 0 to 2 and specifies if the
diversion is presented to the caller. A value of 0 denies
to show the caller that and where the call has been
deflected. Specifying a value of 1 only shows that the
call has been diverted but doesn't show to which final
destination this will happen. A value of 2 lets the caller
know all information of the diversion (fact of diversion
and number diverted to).
insertrule driverid action msn si1 si2 callerid screen
delay option destnumber
This command inserts a single rule at the beginning before
the first already existing rule in the chain. All parame
ters and descriptions are the same as for the appendrule
command.
Numeric codes of basic services
0 all services
1 speech
2 unrestricted digital information
3 audio 3.1 kHz
4 unrestricted digital info with tone announcements
5 multirate
32 telephony 3.1 kHz
33 teletex
34 telefax group 4 class 1
35 videotex syntax based
36 videotelephony
37 telefax group 2/3
38 telephony 7 kHz
39 eurofiletransfer
40 filetransfer and access management
42 audio graphic conference
When diversion of speech calls is desired at least ser
vices 1, 2 and 32 should be specified.
Interfacing to other programs
The /proc/net/isdn/divert device may be used for debug
purposes or interfacing the diversion services to other
programs. It may be multiple opened. All operations as
well as incoming calls may be watched reading the ascii
output of the interface. One possible application would be
a remote client announcing and logging incoming calls and
diversion actions inside the local network. Such logging
service could be invoked via inetd.
BUGS
With some commands an explicit driverid needs to be speci
fied under certain conditions even if wildcards should be
allowed. If you get a core dump using wildcards try to use
a cmd line specifying a single interface. This man page
is still not complete.
AUTHOR
Werner Cornelius <werner@isdn4linux.de or werner@isdn-
development.de>
Man(1) output converted with
man2html