/* -*- 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"

struct lrtp_t;

/**
 * Initialise lrtp.
 * @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);

/**
 * Close session.
 * @param lrtp The lrtp context handle to be closed.
 */
EXPORT
void 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 0 on success, 1 on error.
 */
EXPORT
int 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.
 */
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;

/**
 * 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 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
 * 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
int 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
 * 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);

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.
 * @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. -1 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 0 on success, error code (negative integer) on error.
 */
EXPORT
int lrtp_unpack(struct lrtp_t *lrtp, const char *packet, size_t size);

#ifdef __cplusplus
}
#endif

#endif/*__LRTP_LRTP_H__*/