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 |
|