spandsp  0.0.6
v42.h
1 /*
2  * SpanDSP - a series of DSP components for telephony
3  *
4  * v42.h
5  *
6  * Written by Steve Underwood <steveu@coppice.org>
7  *
8  * Copyright (C) 2003 Steve Underwood
9  *
10  * All rights reserved.
11  *
12  * This program is free software; you can redistribute it and/or modify
13  * it under the terms of the GNU Lesser General Public License version 2.1,
14  * as published by the Free Software Foundation.
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19  * GNU Lesser General Public License for more details.
20  *
21  * You should have received a copy of the GNU Lesser General Public
22  * License along with this program; if not, write to the Free Software
23  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
24  */
25 
26 /*! \page v42_page V.42 modem error correction
27 \section v42_page_sec_1 What does it do?
28 The V.42 specification defines an error correcting protocol for PSTN modems, based on
29 HDLC and LAP. This makes it similar to an X.25 link. A special variant of LAP, known
30 as LAP-M, is defined in the V.42 specification. A means for modems to determine if the
31 far modem supports V.42 is also defined.
32 
33 \section v42_page_sec_2 How does it work?
34 */
35 
36 #if !defined(_SPANDSP_V42_H_)
37 #define _SPANDSP_V42_H_
38 
39 enum
40 {
41  LAPM_DETECT = 0,
42  LAPM_ESTABLISH = 1,
43  LAPM_DATA = 2,
44  LAPM_RELEASE = 3,
45  LAPM_SIGNAL = 4,
46  LAPM_SETPARM = 5,
47  LAPM_TEST = 6,
48  LAPM_UNSUPPORTED = 7
49 };
50 
51 typedef void (*v42_status_func_t)(void *user_data, int status);
52 typedef void (*v42_frame_handler_t)(void *user_data, const uint8_t *pkt, int len);
53 
54 typedef struct lapm_frame_queue_s
55 {
56  struct lapm_frame_queue_s *next;
57  int len;
58  uint8_t frame[];
60 
61 /*!
62  LAP-M descriptor. This defines the working state for a single instance of LAP-M.
63 */
64 typedef struct lapm_state_s lapm_state_t;
65 
66 /*!
67  V.42 descriptor. This defines the working state for a single instance of V.42.
68 */
69 typedef struct v42_state_s v42_state_t;
70 
71 /*! Log the raw HDLC frames */
72 #define LAPM_DEBUG_LAPM_RAW (1 << 0)
73 /*! Log the interpreted frames */
74 #define LAPM_DEBUG_LAPM_DUMP (1 << 1)
75 /*! Log state machine changes */
76 #define LAPM_DEBUG_LAPM_STATE (1 << 2)
77 
78 #if defined(__cplusplus)
79 extern "C"
80 {
81 #endif
82 
83 SPAN_DECLARE(const char *) lapm_status_to_str(int status);
84 
85 /*! Dump LAP.M frames in a raw and/or decoded forms
86  \param frame The frame itself
87  \param len The length of the frame, in octets
88  \param showraw TRUE if the raw octets should be dumped
89  \param txrx TRUE if tx, FALSE if rx. Used to highlight the packet's direction.
90 */
91 SPAN_DECLARE(void) lapm_dump(lapm_state_t *s, const uint8_t *frame, int len, int showraw, int txrx);
92 
93 /*! Accept an HDLC packet
94 */
95 SPAN_DECLARE_NONSTD(void) lapm_receive(void *user_data, const uint8_t *buf, int len, int ok);
96 
97 /*! Transmit a LAP.M frame
98 */
99 SPAN_DECLARE(int) lapm_tx(lapm_state_t *s, const void *buf, int len);
100 
101 /*! Transmit a LAP.M information frame
102 */
103 SPAN_DECLARE(int) lapm_tx_iframe(lapm_state_t *s, const void *buf, int len, int cr);
104 
105 /*! Send a break over a LAP.M connection
106 */
107 SPAN_DECLARE(int) lapm_break(lapm_state_t *s, int enable);
108 
109 /*! Initiate an orderly release of a LAP.M connection
110 */
111 SPAN_DECLARE(int) lapm_release(lapm_state_t *s);
112 
113 /*! Enable or disable loopback of a LAP.M connection
114 */
115 SPAN_DECLARE(int) lapm_loopback(lapm_state_t *s, int enable);
116 
117 /*! Assign or remove a callback routine used to deal with V.42 status changes.
118 */
119 SPAN_DECLARE(void) v42_set_status_callback(v42_state_t *s, v42_status_func_t callback, void *user_data);
120 
121 /*! Process a newly received bit for a V.42 context.
122 */
123 SPAN_DECLARE(void) v42_rx_bit(void *user_data, int bit);
124 
125 /*! Get the next transmit bit for a V.42 context.
126 */
127 SPAN_DECLARE(int) v42_tx_bit(void *user_data);
128 
129 /*! Initialise a V.42 context.
130  \param s The V.42 context.
131  \param calling_party TRUE if caller mode, else answerer mode.
132  \param frame_handler A callback function to handle received frames of data.
133  \param user_data An opaque pointer passed to the frame handler routine.
134  \return ???
135 */
136 SPAN_DECLARE(v42_state_t *) v42_init(v42_state_t *s, int calling_party, int detect, v42_frame_handler_t frame_handler, void *user_data);
137 
138 /*! Restart a V.42 context.
139  \param s The V.42 context.
140 */
141 SPAN_DECLARE(void) v42_restart(v42_state_t *s);
142 
143 /*! Release a V.42 context.
144  \param s The V.42 context.
145  \return 0 if OK */
146 SPAN_DECLARE(int) v42_release(v42_state_t *s);
147 
148 /*! Free a V.42 context.
149  \param s The V.42 context.
150  \return 0 if OK */
151 SPAN_DECLARE(int) v42_free(v42_state_t *s);
152 
153 #if defined(__cplusplus)
154 }
155 #endif
156 
157 #endif
158 /*- End of file ------------------------------------------------------------*/