summaryrefslogtreecommitdiff
path: root/src/lrtp.h
blob: 739f47031e30777cea3c7f4377e8871950022ae3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set et sw=2 ts=2: */
/***************************************************************************
 *            lrtp.h
 *
 *  Mon Sep  2 12:10:40 CEST 2013
 *  Copyright 2013 Bent Bisballe Nyeng
 *  deva@aasimon.org
 ****************************************************************************/

/*
 *  This file is part of lrtp.
 *
 * lrtp is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * lrtp is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with lrtp; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 */
#ifndef __LRTP_LRTP_H__
#define __LRTP_LRTP_H__

#ifdef WIN32
#ifdef BUILD_DLL
/* DLL export */
#define EXPORT __declspec(dllexport)
#else
/* EXE import */
#define EXPORT __declspec(dllimport)
#endif
#else
#define EXPORT
#endif

#ifdef __cplusplus
extern "C" {
#endif

#include <stdlib.h>

#include "lrtp_profiles.h"

/**
 * Status return codes. Note that all of these values (except @ref ERROR_OK)
 * are negative. The reason for this is that many functions return a size or
 * a negative integer (one of these values) in case of error.
 */
enum lrtp_status_t {
  LRTP_OK                 =    0, ///< All went well.
  LRTP_UNKNOWN            =   -1, ///< An unknown error occurred.
  LRTP_MISSING_HANDLE     =   -2, ///< The handle is corrupted or NULL.
  LRTP_OUT_OF_MEMORY      =   -3, ///< Out of memory error.

  // SRTP errors
  LRTP_SRTP_FAIL          =   -4, ///< unspecified failure
  LRTP_SRTP_BAD_PARAM     =   -5, ///< unsupported parameter
  LRTP_SRTP_ALLOC_FAIL    =   -6, ///< couldn't allocate memory
  LRTP_SRTP_DEALLOC_FAIL  =   -7, ///< couldn't deallocate properly
  LRTP_SRTP_INIT_FAIL     =   -8, ///< couldn't initialize
  LRTP_SRTP_TERMINUS      =   -9, ///< can't process as much data as requested
  LRTP_SRTP_AUTH_FAIL     =  -10, ///< authentication failure
  LRTP_SRTP_CIPHER_FAIL   =  -11, ///< cipher failure
  LRTP_SRTP_REPLAY_FAIL   =  -12, ///< replay check failed (bad index)
  LRTP_SRTP_REPLAY_OLD    =  -13, ///< replay check failed (index too old)
  LRTP_SRTP_ALGO_FAIL     =  -14, ///< algorithm failed test routine
  LRTP_SRTP_NO_SUCH_OP    =  -15, ///< unsupported operation
  LRTP_SRTP_NO_CTX        =  -16, ///< no appropriate context found
  LRTP_SRTP_CANT_CHECK    =  -17, ///< unable to perform desired validation
  LRTP_SRTP_KEY_EXPIRED   =  -18, ///< can't use key any more
  LRTP_SRTP_SOCKET_ERR    =  -19, ///< error in use of socket
  LRTP_SRTP_SIGNAL_ERR    =  -20, ///< error in use POSIX signals
  LRTP_SRTP_NONCE_BAD     =  -21, ///< nonce check failed
  LRTP_SRTP_READ_FAIL     =  -22, ///< couldn't read data
  LRTP_SRTP_WRITE_FAIL    =  -23, ///< couldn't write data
  LRTP_SRTP_PARSE_ERR     =  -24, ///< error pasring data
  LRTP_SRTP_ENCODE_ERR    =  -25, ///< error encoding data
  LRTP_SRTP_SEMAPHORE_ERR =  -26, ///< error while using semaphores
  LRTP_SRTP_PFKEY_ERR     =  -27, ///< error while using pfkey

  LRTP_MISSING_CSRC       =  -28, ///< Invalid CSrc

  LRTP_TOO_MANY_CSRCS     =  -29, ///< Exactly one csrc must be present.
  LRTP_MISSING_PROFILE    =  -30, ///< CSrc from packet could not be connected with a profile..
  LRTP_UNPACK_ERROR       =  -31, ///< Error unpacking RTP pakcet.
  LRTP_BUFFER_TOO_SMALL   =  -32, ///< Supplied buffer was not big enough.

  LRTP_CSRC_ALREADY_ACTIVE=  -33, ///< CSrc already in session list.

  LRTP_KEY_TOO_LONG       =  -34, ///< Supplied key string is longer than 64 bytes
  LRTP_INVALID_KEY_STRING =  -35, ///< Supplied key string is not valid hex.
  LRTP_KEY_TOO_SHORT      =  -36, ///< Supplied key string is shorter than 64 bytes.

};

struct lrtp_t;

/**
 * Initialise lrtp.
 * @param status A pointer to the function status code. If the function returns
 *  NULL this status code will indicate what went wrong. If status is NULL it
 *  will simply be ignored.
 * @param key The key to be use in this session.
 * @param ssrc The secure source to be used in the session.
 * @return Returns the handle to the newly created session.
 */
EXPORT
struct lrtp_t *lrtp_init(enum lrtp_status_t *status,
                         const char *key, unsigned int ssrc);

/**
 * Close session.
 * @param lrtp The lrtp context handle to be closed.
 * @return LRTP_OK on success, or LRTP_MISSING_HANDLE if handle was broken or
 *  NULL.
 */
EXPORT
enum lrtp_status_t lrtp_close(struct lrtp_t *lrtp);

/**
 * Create a new profile to be used in the lrtp_enqueue_frame and
 * lrtp_dequeue_frame function calls.
 * The profile is referenced byt ccsrc, so this must be unique to the active
 * session.
 * @param lrtp The lrtp context handle.
 * @param profile_id See lrtp_profiles.h for possible values.
 * @param csrc The csrc to be connected with this profile.
 * @param ... Options for the profile. See lrtp_profiles.h for possible values.
 * @return TODO: TBD
 */
EXPORT
enum lrtp_status_t lrtp_create_profile(struct lrtp_t *lrtp,
                                       lrtp_profile_id_t profile_id,
                                       unsigned int csrc, ...);
  
/**
 * Free all resources connected with a profile.
 * @param lrtp The lrtp context handle.
 * @param csrc The csrc of the profile to be freed.
 * @return TODO: TBD
 */
EXPORT
enum lrtp_status_t lrtp_destroy_profile(struct lrtp_t *lrtp, unsigned int csrc);

enum lrtp_data_flags_t {
  LRTP_NO_FLAGS       = 0,
  LRTP_TAKE_OWNERSHIP = 1,
  LRTP_COPY           = 2,
};

/**
 * Enqueue a media frame for the packetiser.
 * @param profile A pointer to profile needed for processing the frame type.
 * @param framedata The frame data that needs encapsulation.
 * @param framesize The size in bytes of the frame data.
 * @param timestamp TODO: TBD
 * @param flags Controls the data memory ownership behaviour.
 *  See @ref enum lrtp_data_flags_t for possible values.
 * @return TODO: TBD
 * WARNING: The frame pointer cannot be freed or overwritten until all frame
 * data has been handled by lrtp_pack(). Either call lrtp_pack() until it
 * returns 0 after each call to lrtp_enqueue_frame or use the
 * OPTION_SET_PROCESS_FINISHED_HANDLER option to set a process finished handler.
 * See lrtp_profiles.h for further details.
 */
EXPORT
enum lrtp_status_t lrtp_enqueue_frame(struct lrtp_t *lrtp, unsigned int csrc,
                                      char *framedata, size_t framesize,
                                      unsigned long int timestamp,
                                      int flags);

/**
 * Handle frame data from the frame queue and create at most a single sRTP
 * packet.
 * @param lrtp The lrtp context handle.
 * @param packet A char buffer which will contain the resulting RTP data.
 * @param maxsize the maximum number of bytes that can be contained within
 *  packet.
 * @return Returns the number of bytes written in packet, if any (can be zero
 *  if no packet is available) or a negative error code on error.
 */
EXPORT int lrtp_pack(struct lrtp_t *lrtp, char *packet, size_t maxsize);

/**
 * Dequeue a frame from the frame queue.
 * @param lrtp The lrtp context handle.
 * @param frame A pointer to a char buffer in which the frame will be written.
 * @param maxsize The size of the char buffer stored in 'frame'.
 * @param csrc The csrc of the dequeued frame is returned in this pointer.
 * @param ts The timestamp of the dequeued frame is returned in this pointer.
 * @return The size of the returned frame or a negative error code on error.
 */
EXPORT
int lrtp_dequeue_frame(struct lrtp_t *lrtp,
                       char *frame, size_t maxsize,
                       unsigned int *csrc, unsigned int *ts);

/**
 * Unpack packet from UDP stream. The packet will be cached, unpacked and (if a
 * complete frame has been received) be pushed to the frame queue.
 * @param lrtp The lrtp context handle.
 * @param packet The packet data.
 * @param size The size of the packet.
 * @return TODO: TBD
 */
EXPORT
enum lrtp_status_t lrtp_unpack(struct lrtp_t *lrtp,
                               const char *packet, size_t size);

#ifdef __cplusplus
}
#endif

#endif/*__LRTP_LRTP_H__*/