Statistics
| Branch: | Revision:

chunker-player / event_http / chunk_external_interface.h @ 59c85ad1

History | View | Annotate | Download (8.88 KB)

1 59c85ad1 GiuseppeTropea
/**
2
 * @file chunk_external_interface.h
3
 * 
4
 * Interface file for API to push chunks to external video players or pull from video sources.
5
 *
6
 * This is the interface for external chunk generators (i.e. video sources + a chunker)
7
 * or chunk consumers (i.e. an unchunker + video player) to push chunks into
8
 * a peer's internal chunk buffer, or to retrieve chunks from a peer's internal chunk buffer,
9
 * respectively.
10
 * The interface objects use a simple http channel to move chunks out/in of the
11
 * main peer's application, and use a pointer to the chunkbuffer and the necessary
12
 * callbacks.
13
 * This interface is built upon a libevent-based simple http client and server model
14
 * with no threads, thus it is based on callbacks and timer events, as required
15
 * by the current implementation of the peer application.
16
 *
17
 * Napa-Wine project 2009-2010
18
 * @author: Giuseppe Tropea <giuseppe.tropea@lightcomm.it>
19
 */
20
21
#ifndef _CHUNK_EXTERNAL_INTERFACE_H
22
#define _CHUNK_EXTERNAL_INTERFACE_H
23
24
#include <stdio.h>
25
//this depends on libevent for many reasons
26
#include <event-config.h>
27
#include <stdarg.h>
28
#include <sys/types.h>
29
#include <event2/util.h>
30
#include <event2/buffer.h>
31
#include <event2/http.h>
32
#include <event2/http_struct.h>
33
//thus i need a global variable with the external heartbeat and timings
34
extern struct event_base *eventbase;
35
36
//#include "../include/chunk.h"
37
//#include "../include/trade_msg_la.h"
38
//#include "../include/grapes_log.h"
39
#include <chunk.h>
40
//#include <trade_msg_la.h>
41
#include <grapes_log.h>
42
43
#include "ul_commons.h"
44
45
//moreover we are interfacing to the chunkbuffer
46
//we assume for now it is a global variable too
47
extern struct chunk_buffer *chunkbuffer;
48
49
/**
50
 * define a new data type for the pointer to a generic data_processor function
51
 */
52
typedef int (*data_processor_function)(const uint8_t *data, int data_len);
53
54
55
//DOCUMENTATION RELATIVE TO THE CHUNK_RECEIVER.C FILE
56
/**
57
 * Setup of a chunk receiver inside the peer.
58
 *
59
 * The chunk receiver receives chunks from an external application
60
 * via a regular http socket. The chunk receiver listens for chunks at
61
 * a specific address:port on the machine where the peer application
62
 * is running.
63
 * The chunk receiver uses for its internals a simple http server. When the
64
 * server receives a request, a callback is triggered to deal with
65
 * the incoming block of data (i.e. the incoming chunk).
66
 *
67
 * @param[in] address The IP address the receiver shall run at
68
 * @param[in] port The port the receiver shall listen at
69
 * @return 0 if OK, -1 if problems
70
 */
71
int ulChunkReceiverSetup(const char *address, unsigned short port);
72
73
/**
74
 * Callback for processing the received chunk.
75
 *
76
 * This function is called by the http server ProcessRequest function, which is
77
 * in turn triggered whenever a request with a data block is received.
78
 * This function receives from the internal http server the stripped block of bulk
79
 * data and interprets is as a chunk, pushing it into the peer's internal chunk buffer.
80
 *
81
 * @param[in] chunk The data to be processed (a chunk to be inserted into internal chunkbuffer)
82
 * @param[in] chunk_len The chunk length
83
 * @return 0 if OK, -1 if problems
84
 */
85
int ulPushChunkToChunkBuffer_cb(const uint8_t *encoded_chunk, int encoded_chunk_len);
86
87
88
//DOCUMENTATION RELATIVE TO THE EVENT_HTTP_SERVER.C FILE
89
/**
90
 * Sets up the internal http server.
91
 *
92
 * This function sets-up a libevent-based http server listening at a specific address:port.
93
 * When an http request is received by this server, the ProcessRequest callback is triggered,
94
 * which extracts the data embedded in the POST request, strips it and int turn gives it
95
 * to the specific data_processor function passed here in the setup operation.
96
 * Thus this http server is able to call a specific function to take care of
97
 * the received data, depending on who is setting it up.
98
 *
99
 * @param[in] address The IP address the server shall run at
100
 * @param[in] port The port the http server shall listen at
101
 * @param[in] data_processor The external function to call and pass the received data block to
102
 * @return -1 in case of error, when server does not get initialized, 0 if OK
103
 */
104
int ulEventHttpServerSetup(const char *address, unsigned short port, data_processor_function data_processor);
105
106
/**
107
 * Processes the received http request.
108
 *
109
 * Extract the bulk data buffer from the http POST request
110
 * and pass it to an external function for processing it specifically, by giving
111
 * a pointer to the data block and its length
112
 *
113
 * @param[in] req Contains info about the request, from libevent
114
 * @param[in] context A context for this request (an external data_processor function in this case)
115
 * @return -1 in case no data was extracted from the request (bad path, GET insted of POST, etc...), 0 if OK
116
 */
117
int ulEventHttpServerProcessRequest(struct evhttp_request *req, void *context);
118
119
120
//DOCUMENTATION RELATIVE TO THE CHUNK_SENDER.C FILE
121
/**
122
 * Send a chunk to all registered receivers.
123
 *
124
 * The chunk send is called whenever a fresh chunk is inserted into the
125
 * internal chunk buffer of the peer from the P2P network, in order to send
126
 * a copy of the fresh chunk out to external applications, as soon as
127
 * it gets into the peer.
128
 * Generally the fresh chunk is pushed to an external unchunking and video player
129
 * application, or a statistical or analysis application.
130
 * The chunk sender uses a simple regular http client writing to a socket
131
 * for its internal working.
132
 * This chunk sender is triggered via a callback activated by the internal chunk buffer
133
 * receiving a fresh chunk.
134
 * This chunk sender holds a static array of active connections to remote
135
 * applications, and initializes the connections at first time.
136
 *
137
 * @param[in] remote_address The IP address of the external application
138
 * @param[in] remote_port The port of the external application
139
 * @param[out] htc The pointer where the caller wants the connection to be stored
140
 * @return 0 if OK, -1 if problems
141
 */
142
int ulSendChunk(Chunk *c);
143
144
/**
145
 * Send out the chunk to an external application.
146
 *
147
 * This function is passed a chunk and sends it out to an external application via
148
 * the libevent's evhttp_connection object htc.
149
 * This function as of now is just a readability wrapper for the HttpClientPostData
150
 * function of the simple http client code.
151
 *
152
 * @param[in] c The chunk
153
 * @param[in] c_len The chunk length
154
 * @param[in] htc The pointer to the established connection with the external application
155
 * @param path The path within the remote application to push data to
156
 * @return 0 if OK, -1 if problems
157
 */
158
int ulPushChunkToRemoteApplication(Chunk *c, struct evhttp_connection *htc, const char *addr, const int port, const char *path);
159
160
161
//DOCUMENTATION RELATIVE TO THE EVENT_HTTP_CLIENT.C FILE
162
/**
163
 * Sets up a libevent-based http connection to a remote address:port
164
 *
165
 * This is the setup function to create an http socket from this peer to an external
166
 * application waiting for chunks on a specified address:port.
167
 * Pass a pointer to libevent's evhttp_connection object to this function
168
 * in order to get back an handler to the socket connection.
169
 *
170
 * @param[in] address The IP address of the remote http server to connect to
171
 * @param[in] port The port the remote http server is listening at
172
 * @param[out] htc The pointer to where the caller wants the connection pointer to be stored
173
 * @return -1 in case of error, when pointer to connection does not get initialized, 0 if OK
174
 */
175
int ulEventHttpClientSetup(const char *address, unsigned short port, struct evhttp_connection **htc);
176
177
/**
178
 * Post a block of data via http to a remote application.
179
 *
180
 * Performs a POST http request operation towards a remote http server in order to transfer a bulk
181
 * block of bytes to the server entity through the already establised connection.
182
 *
183
 * @param data A pointer to the block of bytes to be transferred
184
 * @param data_len The length of the data block
185
 * @param htc A pointer to the already established libevent-based http connection to the server
186
 * @param path The path within the remote application to push data to
187
 * @return -1 in case of error, or when pointer to connection does not get initialized, 0 if OK
188
 */
189
int ulEventHttpClientPostData(uint8_t *data, unsigned int data_len, struct evhttp_connection *htc, const char *addr, const int port, const char *path);
190
191
192
//DOCUMENTATION RELATIVE TO THE RECEIVERS_REGISTRY.C FILE
193
/**
194
 * Register a new receiver application.
195
 *
196
 * The remote application registers itself by declaring something
197
 * like "http://address:port/path/to/receiver/"
198
 * The function can be used to retrieve information about an already registered
199
 * application at a specific position, by giving NULL inputs except
200
 * for the pos parameter.
201
 *
202
 * @param[in,out] address The application IP address
203
 * @param[in,out] port The application port
204
 * @param[in,out] path The path where to send chunks
205
 * @param[in,out] pos The position in the registration array
206
 * @return 0 if OK, -1 if problems
207
 */
208
int ulRegisterApplication(char *address, int *port, char* path, int *pos);
209
210
211
#endif        /* CHUNK_EXTERNAL_INTERFACE_H */