1 /* 2 en50221 encoder An implementation for libdvb 3 an implementation for the en50221 session layer 4 5 Copyright (C) 2004, 2005 Manu Abraham <abraham.manu@gmail.com> 6 Copyright (C) 2005 Julian Scheel (julian at jusst dot de) 7 Copyright (C) 2006 Andrew de Quincey (adq_dvb@lidskialf.net) 8 9 This library is free software; you can redistribute it and/or modify 10 it under the terms of the GNU Lesser General Public License as 11 published by the Free Software Foundation; either version 2.1 of 12 the License, or (at your option) any later version. 13 14 This program is distributed in the hope that it will be useful, 15 but WITHOUT ANY WARRANTY; without even the implied warranty of 16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 17 GNU Lesser General Public License for more details. 18 19 You should have received a copy of the GNU Lesser General Public 20 License along with this library; if not, write to the Free Software 21 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 22 */ 23 24 25 #ifndef __EN50221_TRANSPORT_H__ 26 #define __EN50221_TRANSPORT_H__ 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif 31 32 #include <stdlib.h> 33 #include <stdint.h> 34 #include <sys/uio.h> 35 36 /** 37 * Callback reasons. 38 */ 39 #define T_CALLBACK_REASON_CONNECTIONOPEN 0x00 // A connection we opened _to_ the cam has been ACKed 40 #define T_CALLBACK_REASON_CAMCONNECTIONOPEN 0x01 // The cam has opened a connection to _us_. 41 #define T_CALLBACK_REASON_DATA 0x02 // Data received 42 #define T_CALLBACK_REASON_CONNECTIONCLOSE 0x03 // The cam has told us to close a connection. 43 #define T_CALLBACK_REASON_SLOTCLOSE 0x04 // The cam in the supplied slot id has been removed. 44 45 // these are the states a TC can be in 46 #define T_STATE_IDLE 0x01 // this transport connection is not in use 47 #define T_STATE_ACTIVE 0x02 // this transport connection is in use 48 #define T_STATE_ACTIVE_DELETEQUEUED 0x04 // this transport connection is about to be deleted 49 #define T_STATE_IN_CREATION 0x08 // this transport waits for a T_C_T_C_REPLY to become active 50 #define T_STATE_IN_DELETION 0x10 // this transport waits for T_D_T_C_REPLY to become idle again 51 52 /** 53 * Opaque type representing a transport layer. 54 */ 55 struct en50221_transport_layer; 56 57 /** 58 * Type definition for callback function - used when events are received from a module. 59 * 60 * **IMPORTANT** For all callback reasons except T_CALLBACK_REASON_DATA, an internal lock is held in the 61 * transport layer. Therefore, to avoid deadlock, you *must not* call back into the transport layer for 62 * these reasons. 63 * 64 * However, for T_CALLBACK_REASON_DATA, the internal lock is not held, so calling back into the transport 65 * layer is fine in this case. 66 * 67 * @param arg Private data. 68 * @param reason One of the T_CALLBACK_REASON_* values. 69 * @param data The data. 70 * @param data_length Length of the data. 71 * @param slot_id Slot_id the data was received from. 72 * @param connection_id Connection_id the data was received from. 73 */ 74 typedef void (*en50221_tl_callback) (void *arg, int reason, 75 uint8_t * data, 76 uint32_t data_length, 77 uint8_t slot_id, 78 uint8_t connection_id); 79 80 81 /** 82 * Construct a new instance of the transport layer. 83 * 84 * @param max_slots Maximum number of slots to support. 85 * @param max_connections_per_slot Maximum connections per slot. 86 * @return The en50221_transport_layer instance, or NULL on error. 87 */ 88 extern struct en50221_transport_layer *en50221_tl_create(uint8_t max_slots, 89 uint8_t max_connections_per_slot); 90 91 /** 92 * Destroy an instance of the transport layer. 93 * 94 * @param tl The en50221_transport_layer instance. 95 */ 96 extern void en50221_tl_destroy(struct en50221_transport_layer *tl); 97 98 /** 99 * Register a new slot with the library. 100 * 101 * @param tl The en50221_transport_layer instance. 102 * @param ca_hndl FD for talking to the slot. 103 * @param slot CAM slot where the requested CAM of the CA is in. 104 * @param response_timeout Maximum timeout in ms to a response we send before signalling a timeout. 105 * @param poll_delay Interval between polls in ms. 106 * @return slot_id on sucess, or -1 on error. 107 */ 108 extern int en50221_tl_register_slot(struct en50221_transport_layer *tl, 109 int ca_hndl, uint8_t slot, 110 uint32_t response_timeout, 111 uint32_t poll_delay); 112 113 /** 114 * Destroy a registered slot - e.g. if a CAM is removed, or an error occurs. Does 115 * not attempt to reset the CAM. 116 * 117 * @param tl The en50221_transport_layer instance. 118 * @param slot_id Slot to destroy. 119 */ 120 extern void en50221_tl_destroy_slot(struct en50221_transport_layer *tl, uint8_t slot_id); 121 122 /** 123 * Performs one iteration of the transport layer poll - 124 * checking for incoming data furthermore it will handle 125 * the timeouts of certain commands like T_DELETE_T_C it 126 * should be called by the application regularly, generally 127 * faster than the poll delay. 128 * 129 * @param tl The en50221_transport_layer instance. 130 * @return 0 on succes, or -1 if there was an error of some sort. 131 */ 132 extern int en50221_tl_poll(struct en50221_transport_layer *tl); 133 134 /** 135 * Register the callback for data reception. 136 * 137 * @param tl The en50221_transport_layer instance. 138 * @param callback The callback. Set to NULL to remove the callback completely. 139 * @param arg Private data passed as arg0 of the callback. 140 */ 141 extern void en50221_tl_register_callback(struct en50221_transport_layer *tl, 142 en50221_tl_callback callback, void *arg); 143 144 /** 145 * Gets the ID of the slot an error occurred on. 146 * 147 * @param tl The en50221_transport_layer instance. 148 * @return The offending slot id. 149 */ 150 extern int en50221_tl_get_error_slot(struct en50221_transport_layer *tl); 151 152 /** 153 * Gets the last error. 154 * 155 * @param tl The en50221_transport_layer instance. 156 * @return One of the EN50221ERR_* values. 157 */ 158 extern int en50221_tl_get_error(struct en50221_transport_layer *tl); 159 160 /** 161 * This function is used to take a data-block, pack into 162 * into a TPDU (DATA_LAST) and send it to the device 163 * 164 * @param tl The en50221_transport_layer instance. 165 * @param slot_id ID of the slot. 166 * @param connection_id Connection id. 167 * @param data Data to send. 168 * @param data_length Number of bytes to send. 169 * @return 0 on success, or -1 on error. 170 */ 171 extern int en50221_tl_send_data(struct en50221_transport_layer *tl, 172 uint8_t slot_id, 173 uint8_t connection_id, 174 uint8_t * data, 175 uint32_t data_length); 176 177 /** 178 * This function is used to take a data-block, pack into 179 * into a TPDU (DATA_LAST) and send it to the device 180 * 181 * @param tl The en50221_transport_layer instance. 182 * @param slot_id ID of the slot. 183 * @param connection_id Connection id. 184 * @param vector iov to send. 185 * @param io_count Number of elements in vector. 186 * @return 0 on success, or -1 on error. 187 */ 188 extern int en50221_tl_send_datav(struct en50221_transport_layer *tl, 189 uint8_t slot_id, uint8_t connection_id, 190 struct iovec *vector, int iov_count); 191 192 /** 193 * Create a new transport connection to the cam. 194 * 195 * **IMPORTANT** When this function returns, it means the request to create a connection 196 * has been submitted. You will need to poll using en50221_tl_get_connection_state() to find out 197 * if/when the connection is established. A callback with T_CALLBACK_REASON_CONNECTIONOPEN reason 198 * will also be sent when it is acked by the CAM. 199 * 200 * @param tl The en50221_transport_layer instance. 201 * @param slot_id ID of the slot. 202 * @return The allocated connection id on success, or -1 on error. 203 */ 204 extern int en50221_tl_new_tc(struct en50221_transport_layer *tl, uint8_t slot_id); 205 206 /** 207 * Deallocates a transport connection. 208 * 209 * **IMPORTANT** When this function returns, it means the request to destroy a connection 210 * has been submitted. You will need to poll using en50221_tl_get_connection_state() to find out 211 * if/when the connection is destroyed. 212 * 213 * @param tl The en50221_transport_layer instance. 214 * @param slot_id ID of the slot. 215 * @param connection_id Connection id to send the request _on_. 216 * @return 0 on success, or -1 on error. 217 */ 218 extern int en50221_tl_del_tc(struct en50221_transport_layer *tl, uint8_t slot_id, uint8_t connection_id); 219 220 /** 221 * Checks the state of a connection. 222 * 223 * @param tl The en50221_transport_layer instance. 224 * @param slot_id ID of the slot. 225 * @param connection_id Connection id to send the request _on_. 226 * @return One of the T_STATE_* values. 227 */ 228 extern int en50221_tl_get_connection_state(struct en50221_transport_layer *tl, 229 uint8_t slot_id, uint8_t connection_id); 230 231 #ifdef __cplusplus 232 } 233 #endif 234 #endif 235