Revision 507372bb include/ul.h

View differences:

include/ul.h
3 3

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

  
41 41
 * `Roughly correct timing'  means that the sending time for chunks are synchronized 
42 42
 * (to the media time they contain) with an accuracy of about or less than one chunk period. 
43
 * This way, within GRAPES, new chunks may directly enter the ChunkBuffer (replacing the oldest one), 
43
 * This way, within the application, new chunks may directly enter the ChunkBuffer (replacing the oldest one), 
44 44
 * and the dechunkizers will also have to buffer only a small number of (1-3) chunks. 
45 45
 * 
46 46
 * For low-level interface, we propose using HTTP POST operations: HTTP is a well-known protocol 
......
49 49
 * HTTP interfaces are also easy to test.
50 50
 * 
51 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 GRAPES is the same HTTP 
52
 * on the receiver side. The service offered for this registration by the application is the same HTTP 
53 53
 * service used by the chunkizer to send new chunks.
54 54
 *
55 55
 * <b> Source (ingestor) Protocol Description</b>
......
58 58
 * from the ingestor. The format is a follows:<br>
59 59
 * <tt>http://<addr>:<port>/<path-id>/<chunk-number>?timestamp=<date></tt><br>
60 60
 * accompanied by the binary chunk in the POST message
61
 * The chunk data is opaque for GRAPES and is delivered unchanged.
61
 * The chunk data is opaque for the application and is delivered unchanged.
62 62
 *
63 63
 * <b> Player (client) Protocol Description: Control Interface</b>
64 64
 * 
65
 * The GRAPES core module implements a HTTP listener to receive registrations
65
 * An application module implements a HTTP listener to receive registrations
66 66
 * from clients (e.g. Display/GUI or analyzer modules). 
67 67
 * Registrations are encoded as HTTP GET requests as follows:
68 68
 * <tt>http://<hostname>:<port>/register-receptor?url=<url>&channel=<channel>&delay=<delay>&validity=<validity></tt><br>
69 69
 * Parameters are:
70
 *	- <hostname> and <port> are startup parameters for GRAPES
70
 *	- <hostname> and <port> are startup parameters for the application
71 71
 *	- <url> the URL where posts should be sent (URL encoded). MANDATORY.
72 72
 *	- <channel> channel identifier
73 73
 * 	- <delay> the delay, expressed in seconds, fractional values are supported. Delay defaults to 5 seconds.
74 74
 * 	- <validity> TImeout for this registration: if there is no additional registration 
75
 *	within <validity> seconds, GRAPES will stop posting chunks.  Default is 300 seconds.
75
 *	within <validity> seconds, the application will stop posting chunks.  Default is 300 seconds.
76 76
 * 
77 77
 * Then, each registered client module is supposed to implement a HTTP listener on the specified URL  
78
 * where GRAPES will send chunks to. Sending is implemented as a HTTP POST using the source (ingestor) protocol
78
 * where the application will send chunks to. Sending is implemented as a HTTP POST using the source (ingestor) protocol
79 79
 * above.
80 80
 * The client-registration HTTP service above can be easily extended with optional commands implementing GUI
81 81
 * controls.
......
88 88
 * 
89 89
 */
90 90

  
91
#include	"grapes.h"
91
#include	"napa.h"
92 92

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

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

Also available in: Unified diff