Statistics
| Branch: | Revision:

napa-baselibs / include / ul.h @ 507372bb

History | View | Annotate | Download (5.47 KB)

1
#ifndef _UL_H
2
#define _UL_H
3

    
4
/** @file ul.h
5
 * 
6
 * @brief User Layer Interface 
7
 * 
8
 * The User Layer API describes how a peer interacts with the user.
9
 * There are two major operation modes:
10
 *        - player: displays the received video stream, and provides basic 
11
 *                controls (e.g. start/stop, channel switch etc.)
12
 *        - source: each video stream shared has a single source, where it
13
 *                enters the network (<i>ingested</i> by the P2P network).
14
 *
15
 * The main task for the source node is to tranlsate the video streams into
16
 * <i>chunks</i>, ready to be transmitted over to other peers.
17
 * Conversely, `player' nodes need to reconstruct the stream from the chunks
18
 * received.
19
 * These operations are referred to as <i>chunkization</i>/<i>de-chunkization</i>.
20
 * 
21
 * In order to provide maximum flexibility, these processes are loosely coupled 
22
 * to the core via network pipes. For simplicity, in the reference 
23
 * implementation we propose the HTTP protocol for (de)chunkizer-core
24
 * interaction.
25
 *
26
 * This interface is conceptually clean, easy to integrate with other programs, 
27
 * and straightforward to implement.
28
 *
29
 * As a princile to start with, the application handles chunks on its external interfaces. 
30
 * At the ingestion side, it receives chunks sent by a <i>sequencer</i> in approximately correct timing. 
31
 * At the receiver/player nodes, the application should issue chunks in correct sequence, 
32
 * and (if possible) again with a roughly correct timing. 
33
 * As a simple approach, each receiver/player client may request a delay 
34
 * when it connects to the application (e.g. 5 secs), and it receives the replay of 
35
 * ingestion events offset by this delay.
36
 * 
37
 * This approach also decouples the `network' and `multimedia' aspects of the software: 
38
 * the player and ingestor are not linked with the application and has maximum flexibility 
39
 * (e.g. with codec legal and technology aspects).
40

41
 * `Roughly correct timing'  means that the sending time for chunks are synchronized 
42
 * (to the media time they contain) with an accuracy of about or less than one chunk period. 
43
 * This way, within the application, new chunks may directly enter the ChunkBuffer (replacing the oldest one), 
44
 * and the dechunkizers will also have to buffer only a small number of (1-3) chunks. 
45
 * 
46
 * For low-level interface, we propose using HTTP POST operations: HTTP is a well-known protocol 
47
 * supported by many  languages and platforms. Also, due to the transactional nature of HTTP, 
48
 * the boundaries between chunks are clear (as opposed to pipes or TCP sockets). 
49
 * HTTP interfaces are also easy to test.
50
 * 
51
 * The application may support  multiple simultaneous clients (players with different delays, analyzers, etc.) 
52
 * on the receiver side. The service offered for this registration by the application is the same HTTP 
53
 * service used by the chunkizer to send new chunks.
54
 *
55
 * <b> Source (ingestor) Protocol Description</b>
56
 *
57
 * The source module implements a HTTP listenerwhere it receives regular HTTP POST requests
58
 * from the ingestor. The format is a follows:<br>
59
 * <tt>http://<addr>:<port>/<path-id>/<chunk-number>?timestamp=<date></tt><br>
60
 * accompanied by the binary chunk in the POST message
61
 * The chunk data is opaque for the application and is delivered unchanged.
62
 *
63
 * <b> Player (client) Protocol Description: Control Interface</b>
64
 * 
65
 * An application module implements a HTTP listener to receive registrations
66
 * from clients (e.g. Display/GUI or analyzer modules). 
67
 * Registrations are encoded as HTTP GET requests as follows:
68
 * <tt>http://<hostname>:<port>/register-receptor?url=<url>&channel=<channel>&delay=<delay>&validity=<validity></tt><br>
69
 * Parameters are:
70
 *        - <hostname> and <port> are startup parameters for the application
71
 *        - <url> the URL where posts should be sent (URL encoded). MANDATORY.
72
 *        - <channel> channel identifier
73
 *         - <delay> the delay, expressed in seconds, fractional values are supported. Delay defaults to 5 seconds.
74
 *         - <validity> TImeout for this registration: if there is no additional registration 
75
 *        within <validity> seconds, the application will stop posting chunks.  Default is 300 seconds.
76
 * 
77
 * Then, each registered client module is supposed to implement a HTTP listener on the specified URL  
78
 * where the application will send chunks to. Sending is implemented as a HTTP POST using the source (ingestor) protocol
79
 * above.
80
 * The client-registration HTTP service above can be easily extended with optional commands implementing GUI
81
 * controls.
82
 *
83
 * @author Arpad Bakay                        <arpad.bakay@netvisor.hu>
84
 * @author Tivadar Szemethy                <tivadar.szemethy@netvisor.hu>
85
 * @author Giuseppe Tropea                <giuseppe.tropea@lightcomm.it>
86
 *
87
 * @date 01/13/2010
88
 * 
89
 */
90

    
91
#include        "napa.h"
92

    
93
/**
94
  Initialize source functionality within a peer's User Layer.
95

96
  @param[in] ingest_url URL where the node listens for the chunks from the ingestor
97
  @return a handle for the initized source UL or NULL on error
98
*/
99
HANDLE initULSource(const char *ingestor_url);
100

    
101
/**
102
  Shut down a source peer's User Layer.
103

104
  @param ul_source source instance to shut down
105
  @see initULSource
106
*/
107
void shutdownULSource(HANDLE ul_source);
108

    
109

    
110
/**
111
  Initialize a `player' (dechunkizer) functionality  within a peer's User Layer..
112

113
  @param[in] reg_url register-receptor URL where the application listens
114
  @return a handle for the initized peer UL or NULL on error
115
*/
116
HANDLE initULPeer(const char *reg_url);
117

    
118
/**
119
  Shut down a regular peer's User Layer.
120

121
  @param ul_peer peer instance to shut down
122
  @see initULPeer
123
*/
124
void shutdownULPeer(HANDLE ul_peer);
125

    
126
#endif
127