/* -*- 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 #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__*/