diff options
Diffstat (limited to 'src/lrtp.h')
| -rw-r--r-- | src/lrtp.h | 102 |
1 files changed, 70 insertions, 32 deletions
@@ -48,23 +48,76 @@ extern "C" { #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. +}; + 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(const char *key, unsigned int ssrc); +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 -void lrtp_close(struct lrtp_t *lrtp); +enum lrtp_status_t lrtp_close(struct lrtp_t *lrtp); /** * Create a new profile to be used in the lrtp_enqueue_frame and @@ -75,34 +128,28 @@ void lrtp_close(struct lrtp_t *lrtp); * @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 0 on success, 1 on error. + * @return TODO: TBD */ EXPORT -int lrtp_create_profile(struct lrtp_t *lrtp, - lrtp_profile_id_t profile_id, - unsigned int csrc, ...); - +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 -void lrtp_destroy_profile(struct lrtp_t *lrtp, unsigned int csrc); - -typedef enum { - // Errors: - PACK_ERROR = 1000, // Error... - PACK_BUFFER_TOO_SMALL = 1001, // Packet buffer needs to be bigger. - PACK_UNKNOWN_PROFILE = 1002, // Illegal profile id - PACK_MISSING_PROFILE = 1003, // Profile pointer NULL or not valid. -} lrtp_pack_status_t; +enum lrtp_status_t lrtp_destroy_profile(struct lrtp_t *lrtp, unsigned int csrc); /** * Enqueue a media frame for the packetiser. * @param profile A pointer to profile needed for processing the frame type. * @param framedate The frame data that needs encapsulation. * @param framesize The size in bytes of the frame data. + * @return TODO: TBD * @return 0 on success, or a negative error code on error. * 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 @@ -111,9 +158,9 @@ typedef enum { * See lrtp_profiles.h for further details. */ EXPORT -int lrtp_enqueue_frame(struct lrtp_t *lrtp, unsigned int csrc, - char *framedate, size_t framesize, - unsigned long int timestamp); +enum lrtp_status_t lrtp_enqueue_frame(struct lrtp_t *lrtp, unsigned int csrc, + char *framedate, size_t framesize, + unsigned long int timestamp); /** * Handle frame data from the frame queue and create at most a single sRTP @@ -127,16 +174,6 @@ int lrtp_enqueue_frame(struct lrtp_t *lrtp, unsigned int csrc, */ EXPORT int lrtp_pack(struct lrtp_t *lrtp, char *packet, size_t maxsize); -typedef enum { - // Errors: - UNPACK_ERROR = 1000, // Error... - UNPACK_BUFFER_TOO_SMALL = 1001, // Frame buffer needs to be bigger. - UNPACK_MISSING_HANDLE = 1002, // Handle pointer NULL or not valid. - UNPACK_MISSING_CSRC = 1003, // Exactly one csrc must be present. - UNPACK_TOO_MANY_CSRCS = 1004, // Exactly one csrc must be present. - UNPACK_MISSING_PROFILE = 1005, // CSrc from packet could not be connected with a profile.. -} lrtp_unpack_status_t; - /** * Dequeue a frame from the frame queue. * @param lrtp The lrtp context handle. @@ -144,7 +181,7 @@ typedef enum { * @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. -1 on error. + * @return The size of the returned frame or a negative error code on error. */ EXPORT int lrtp_dequeue_frame(struct lrtp_t *lrtp, @@ -157,10 +194,11 @@ int lrtp_dequeue_frame(struct lrtp_t *lrtp, * @param lrtp The lrtp context handle. * @param packet The packet data. * @param size The size of the packet. - * @return 0 on success, error code (negative integer) on error. + * @return TODO: TBD */ EXPORT -int lrtp_unpack(struct lrtp_t *lrtp, const char *packet, size_t size); +enum lrtp_status_t lrtp_unpack(struct lrtp_t *lrtp, + const char *packet, size_t size); #ifdef __cplusplus } |