capi20.3

.\" Copyright (c) 2003 Thomas Wintergerst
.\" Copyright (c) 2005 Hans Petter Selasky
.\"
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: $
.\" $Id: capi20.3,v 1.4.4.1 2005/05/27 16:29:15 thomas Exp $
.\" Creation date       04.01.2003
.\"
.Dd September 6, 2014
.Dt CAPI20 3
.Os
.Sh NAME
.
.
.Nm capi20_be_alloc_client,
.Nm capi20_be_alloc_bintec,
.Nm capi20_be_alloc_i4b,
.Nm capi20_be_socket_configure,
.Nm capi20_be_free,
.Nm capi20_register ,
.Nm capi20_release ,
.Nm capi20_put_message ,
.Nm capi20_get_message ,
.Nm capi20_wait_for_message ,
.Nm capi20_get_manufacturer ,
.Nm capi20_get_version ,
.Nm capi20_get_serial_number ,
.Nm capi20_get_profile ,
.Nm capi20_is_installed ,
.Nm capi20_fileno ,
.Nm capi20_encode ,
.Nm capi20_decode ,
.Nm capi20_get_errstr ,
.Nm capi20_command_pack ,
.Nm capi20_command_unpack
.Nd "CAPI 2.0 access library"
.
.
.Sh LIBRARY
.
.
CAPI 2.0 Access Library (libcapi20, -lcapi20)
.
.
.
.Sh SYNOPSIS
.
.
.In i4b/include/capi20.h
.
.Ft "uint16_t"
.Fo "capi20_be_alloc_client"
.Fa "struct capi20_backend **cbe_pp"
.Fc
.
.Ft "uint16_t"
.Fo "capi20_be_alloc_bintec"
.Fa "struct capi20_backend **cbe_pp"
.Fc
.
.
.Ft "uint16_t"
.Fo "capi20_be_alloc_i4b"
.Fa "struct capi20_backend **cbe_pp"
.Fc
.
.
.Ft "uint16_t"
.Fo "capi20_be_socket_configure"
.Fa "struct capi20_backend *cbe"
.Fa "const char *hostname"
.Fa "const char *portname"
.Fa "const char *username"
.Fa "const char *password"
.Fc
.
.
.Ft "void"
.Fo "capi20_be_free"
.Fa "struct capi20_backend *cbe"
.Fc
.
.
.Ft "uint16_t"
.Fo "capi20_register"
.Fa "struct capi20_backend *cbe"
.Fa "uint32_t max_logical_connections"
.Fa "uint32_t max_b_data_blocks"
.Fa "uint32_t max_b_data_len"
.Fa "uint32_t capi_stack_version"
.Fa "uint32_t *app_id_ptr"
.Fc
.
.
.Ft "uint16_t"
.Fo "capi20_release"
.Fa "uint32_t app_id"
.Fc
.
.
.Ft "uint16_t"
.Fo "capi20_put_message"
.Fa "uint32_t app_id"
.Fa "void *buf_ptr"
.Fc
.
.
.Ft "uint16_t "
.Fo "capi20_get_message"
.Fa "uint32_t app_id"
.Fa "uint8_t **buf_pp"
.Fc
.
.
.Ft "uint16_t"
.Fo "capi20_wait_for_message"
.Fa "uint32_t app_id"
.Fa "struct timeval *timeval_ptr"
.Fc
.
.
.Ft "uint16_t"
.Fo "capi20_get_manufacturer"
.Fa "struct capi20_backend *cbe"
.Fa "uint32_t controller"
.Fa "char *buf_ptr"
.Fa "uint16_t buf_len"
.Fc
.
.
.Ft "uint16_t"
.Fo "capi20_get_version"
.Fa "struct capi20_backend *cbe"
.Fa "uint32_t controller"
.Fa "char *buf_ptr"
.Fa "uint16_t buf_len"
.Fc
.
.
.Ft "uint16_t"
.Fo "capi20_get_serial_number"
.Fa "struct capi20_backend *cbe"
.Fa "uint32_t controller"
.Fa "char *buf_ptr"
.Fa "uint16_t buf_len"
.Fc
.
.
.Ft "uint16_t "
.Fo "capi20_get_profile"
.Fa "struct capi20_backend *cbe"
.Fa "uint32_t controller"
.Fa "void *buf_ptr"
.Fa "uint16_t buf_len"
.Fc
.
.
.Ft "uint16_t"
.Fo "capi20_is_installed"
.Fa "struct capi20_backend *cbe"
.Fc
.
.
.Ft "int"
.Fo "capi20_fileno"
.Fa "uint32_t app_id"
.Fc
.
.
.Ft "uint16_t"
.Fo "capi20_encode"
.Fa "void *ptr"
.Fa "uint16_t len"
.Fa "void *ie"
.Fc
.
.
.Ft "uint16_t"
.Fo "capi20_decode"
.Fa "void *ptr"
.Fa "uint16_t len"
.Fa "void *ie"
.Fc
.
.
.Ft "const char *"
.Fo "capi20_get_errstr"
.Fa "uint16_t wError"
.Fc
.
.Ft "uint16_t"
.Fo "capi20_command_pack"
.Fa "uint16_t wCmd"
.Fc
.
.Ft "uint16_t"
.Fo "capi20_command_unpack"
.Fa "uint16_t wCmd"
.Fc
.
.Sh DESCRIPTION
.
.
The functions described in this manual make up the CAPI implementation
for user space applications in the BSD operating system
environment. They are implemented in the shared library
.Nm libcapi20 .
The functions are largely compatible with the CAPI specification for
other operating systems. There are only minor differences.
.
.
.
.Pp
.
.Fn capi20_be_alloc_client
will create a new CAPI backend that can be used with a the capiserver application.
It returns zero on success. The pointer to the new backend is stored
at the address pointed to by the
.Fa cbe_pp
parameter.
.
.
.
.Pp
.
.Fn capi20_be_socket_configure
will configure the socket based CAPI backends.
The
.Fa hostname ,
.Fa portname ,
.Fa username
and
.Fa password
arguments will be stored in the backed and used when registering
applications.
If an argument is NULL, defaults will be used.
The string length limitations are 64, 16, 64 and 64 characters
respectivly including the termination zero for the arguments.
The
.Fa hostname
and 
.Fa portname 
parameters are forwarded to 
.Xr getaddrinfo 3 .
.
.
.
.Pp
.
.Fn capi20_be_alloc_bintec
will create a new CAPI backend that can be used with a BinTec remote
CAPI router. It returns zero on success. The pointer to the new
backend is stored at the address pointed to by the
.Fa cbe_pp
parameter.
.
.
.
.Pp
.
.Fn capi20_be_alloc_i4b
will create a new CAPI backend that can be used with the I4B kernel
CAPI. It returns zero on success. The pointer to the new backend is
stored at the address pointed to by the
.Fa cbe_pp
parameter.
.
.
.Pp
.
.Fn capi20_be_free
will free a CAPI backend. When a CAPI backend is not passed like an
argument to any function, then it can be freed by a call to this
function.
.
.
.
.Pp
.
.Fn capi20_register
will register a CAPI application. It returns zero on success.  The
application ID is stored in the 32-bit unusigned integer pointed to by
the
.Fa app_id_ptr
parameter. The
.Fa capi_stack_version
parameter should be equal to the macro
.Fa CAPI_STACK_VERSION
defined in
.Pa capi20.h .
It's purpose is to detect CAPI 2.0 API changes, which require software
re-compile.
.Nm libcapi20
will compare the stack version with its internal compiled value and
then against the kernel. If not all are equal,
.Fn capi20_register
will return an
.Fa CAPI_ERROR_UNSUPPORTED_VERSION
error.
.
.
.
.Pp
.
.Fn capi20_release
will release the CAPI application identified by
.Fa app_id
and all resources and active calls associated with it. It returns zero
on success.
.
.
.
.Pp
.
.Fn capi20_put_message
will send a message for the CAPI application identified by
.Fa app_id .
.Fa buf_ptr
is a pointer to the CAPI message that should be sent. If this function
returns non-zero, the application should release its ID and restart.
.
.
.
.Pp
.
.Fn capi20_get_message
will receive a message for the CAPI application identified by
.Fa app_id .
It returns zero on success. If there are no messages and non-blocking
operation is selected,
.Fa CAPI_ERROR_GET_QUEUE_EMPTY
will be returned. Else there is a critical
error and the application should release its ID and restart.
.Fa buf_pp
is a pointer to a pointer that should be pointed to the start of the
received CAPI message.
.
.
.
.Pp
.
.Fn capi20_wait_for_message 
will wait until there is a message for the CAPI application identified by
.Fa app_id .
If 
.Fa timeval_ptr
is not NULL, it will return after that the time indicated by
.Fa timeval_ptr
has elapsed. Zero is returned if a message is available.  Else an
error is returned.
.
.
.
.Pp
.
.Fn capi20_get_manufacturer
will store the manufacturer name as a zero terminated string, for the
CAPI controller identified by
.Fa controller,
in the buffer pointed to by
.Fa buf_ptr
which has length
.Fa buf_len.
Default length is 64 bytes. Zero is returned on success.
.
.
.
.Pp
.
.Fn capi20_get_version
will store the CAPI version like a series of bytes, for the CAPI
backend identified by
.Fa cbe,
in the buffer pointed to by
.Fa buf_ptr
which has length
.Fa buf_len.
Zero is returned on success.
.
.
.
.Pp
.
.Fn capi20_get_serial_number
will store the CAPI serial number as a zero terminated string, for
the CAPI backend identified by
.Fa cbe, 
in the buffer pointed to by
.Fa buf_ptr
which has length
.Fa buf_len.
Default length is 4 bytes. Zero is returned on success.
.
.
.
.Pp
.
.Fn capi20_get_profile
will store the CAPI profile structure, for the CAPI backend identified
by
.Fa cbe, 
in the buffer pointed to by
.Fa buf_ptr
which has length
.Fa buf_len. 
Default length is 64 bytes. Note that the CAPI profile structure uses
little endian byte order. To decode fields use "le16toh()" and
"le32toh()". Zero is returned on success. Also see CAPI_PROFILE_DATA
in
.Pa capi20.h .
.
.
.
.Pp
.
.Fn capi20_is_installed
will return zero if CAPI is installed for the backend given by
.Fa cbe .
Else
.Fa CAPI_ERROR_CAPI_NOT_INSTALLED
is returned.
.
.
.
.Pp
.
.Fn capi20_fileno
will return the file number for the CAPI application identified by
.Fa app_id .
The file number returned can be used for polling. It is also possible
to use the ioctl "FIONBIO" to set or clear non-blocking behaviour. An
integer greater than zero is returned on success.
.
.
.
.Pp
.
.Fn capi20_encode
will encode the *DECODED CAPI message structure pointed to by
.Fa ie
into the buffer pointed to by
.Fa ptr
and
.Fa len .
The function returns the amount of actual buffer space used which
is always less than or equal to the given
.Fa len
argument.
.
.
.
.Pp
.
.Fn capi20_decode
will decode the buffer pointed to by
.Fa ptr
and
.Fa len
into the *DECODED CAPI message structure pointed to by
.Fa ie .
The function returns the actual amount of data decoded which is always
less than or equal to the given
.Fa len
argument.
.
.
.
.Pp
.
.Fn capi20_get_errstr
will return a pointer to a static constant zero terminated ASCII
string describing the numerical 16-bit error code
.Fa wError .
.
.
.Pp
.Fn capi20_command_pack
will pack the given CAPI command. See CAPI_P_XXX() macros.
.
.
.Pp
.Fn capi20_command_unpack
will unpack the given CAPI command. See CAPI_XXX() macros.
.
.
.
.Sh IMPLEMENTATION NOTES
.
.
Definition of CAPI messages and related structures can be found in the header file
.Pa capi20.h .
To make implementing CAPI easier, there has been defined as set of
helper functions that will encode and decode CAPI messages into
predefined structures. These are for example
.Fn capi_get_message_decoded
and
.Fn capi_put_message_decoded .
See also "struct capi_message_decoded". By default all encoded CAPI
structures use little endian byte order.
.
.
.
.
.
.Sh RETURN VALUES
.
.
Nearly all functions return a 16-bit unsigned integer value as a
direct function result.
.Fn capi20_get_errstr()
will return a zero terminated string that describes the return
value. In general a return value of zero means no error.
.Pp
.Bl -tag
.It 0x0000
No error, data is available (default).
.
.It CAPI_ERROR_CAPI_NOT_INSTALLED = 0x1009
The CAPI20 device, /dev/capi20, cannot be opened.
.
.It CAPI_ERROR_OS_RESOURCE_ERROR = 0x1008
The kernel or libcapi20 cannot allocate required memory.
.
.It CAPI_ERROR_ILLEGAL_MSG_PARAMETER = 0x2007
.
.It CAPI_ERROR_INVALID_PARAM = 0x10F0
An invalid parameter was passed to the function.
.
.It CAPI_ERROR_INVALID_APPLICATION_ID = 0x1101
The application ID does not exist. This can be an indication that the CAPI
application was shut down due to lack of free memory in the
kernel. The software has to restart.
.
.It CAPI_ERROR_INVALID_BUFFER_SIZE = 0x1003
.
.It CAPI_ERROR_UNSUPPORTED_VERSION = 0x10F1
The software or the CAPI20 library must be recompiled. One might have
to re-install the CAPI20 header files to /usr/include.
.
.It CAPI_ERROR_BUSY = 0x1007
There is no data buffer where the message can be stored.
.
.It CAPI_ERROR_GET_QUEUE_EMPTY = 0x1104
No CAPI message is available.
.
.
.El
.
.
.
.
.Sh FILES
.
.
/dev/capi20
.Sh SEE ALSO
.Xr i4b 4 ,
.Xr isdnd 8
.Rs
.%Q "CAPI Association e.V."
.%B "Common ISDN API v2.0 4th Edition"
.%D "June 2001"
.%O see http://www.capi.org
.Re
.Sh STANDARDS
The functions described in this manual page largely comply with the
currently existing CAPI specification. Not all features of the CAPI
specification have been implemented.
.
.
.
.Sh AUTHORS
.
.
This
manual page was initially written by
.An Thomas Wintergerst Aq twinterg@gmx.de
and updated by
.An Hans Petter Selasky Aq hselasky@c2i.net
.
.