Statistics
| Branch: | Revision:

chunker-player / event_http / chunk_external_interface.h @ 74310610

History | View | Annotate | Download (8.97 KB)

1
/**
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/napa_log.h"
39
#include <chunk.h>
40
//#include <trade_msg_la.h>
41
#include <napa_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] path The http server will process only requests sent to this path.
102
 * @param[in] data_processor The external function to call and pass the received data block to
103
 * @return -1 in case of error, when server does not get initialized, 0 if OK
104
 */
105
int ulEventHttpServerSetup(const char *address, unsigned short port, const char *path, data_processor_function data_processor);
106

    
107
/**
108
 * Processes the received http request.
109
 *
110
 * Extract the bulk data buffer from the http POST request
111
 * and pass it to an external function for processing it specifically, by giving
112
 * a pointer to the data block and its length
113
 *
114
 * @param[in] req Contains info about the request, from libevent
115
 * @param[in] context A context for this request (an external data_processor function in this case)
116
 * @return -1 in case no data was extracted from the request (bad path, GET insted of POST, etc...), 0 if OK
117
 */
118
int ulEventHttpServerProcessRequest(struct evhttp_request *req, void *context);
119

    
120

    
121
//DOCUMENTATION RELATIVE TO THE CHUNK_SENDER.C FILE
122
/**
123
 * Send a chunk to all registered receivers.
124
 *
125
 * The chunk send is called whenever a fresh chunk is inserted into the
126
 * internal chunk buffer of the peer from the P2P network, in order to send
127
 * a copy of the fresh chunk out to external applications, as soon as
128
 * it gets into the peer.
129
 * Generally the fresh chunk is pushed to an external unchunking and video player
130
 * application, or a statistical or analysis application.
131
 * The chunk sender uses a simple regular http client writing to a socket
132
 * for its internal working.
133
 * This chunk sender is triggered via a callback activated by the internal chunk buffer
134
 * receiving a fresh chunk.
135
 * This chunk sender holds a static array of active connections to remote
136
 * applications, and initializes the connections at first time.
137
 *
138
 * @param[in] remote_address The IP address of the external application
139
 * @param[in] remote_port The port of the external application
140
 * @param[out] htc The pointer where the caller wants the connection to be stored
141
 * @return 0 if OK, -1 if problems
142
 */
143
int ulSendChunk(Chunk *c);
144

    
145
/**
146
 * Send out the chunk to an external application.
147
 *
148
 * This function is passed a chunk and sends it out to an external application via
149
 * the libevent's evhttp_connection object htc.
150
 * This function as of now is just a readability wrapper for the HttpClientPostData
151
 * function of the simple http client code.
152
 *
153
 * @param[in] c The chunk
154
 * @param[in] c_len The chunk length
155
 * @param[in] htc The pointer to the established connection with the external application
156
 * @param path The path within the remote application to push data to
157
 * @return 0 if OK, -1 if problems
158
 */
159
int ulPushChunkToRemoteApplication(Chunk *c, struct evhttp_connection *htc, const char *addr, const int port, const char *path);
160

    
161

    
162
//DOCUMENTATION RELATIVE TO THE EVENT_HTTP_CLIENT.C FILE
163
/**
164
 * Sets up a libevent-based http connection to a remote address:port
165
 *
166
 * This is the setup function to create an http socket from this peer to an external
167
 * application waiting for chunks on a specified address:port.
168
 * Pass a pointer to libevent's evhttp_connection object to this function
169
 * in order to get back an handler to the socket connection.
170
 *
171
 * @param[in] address The IP address of the remote http server to connect to
172
 * @param[in] port The port the remote http server is listening at
173
 * @param[out] htc The pointer to where the caller wants the connection pointer to be stored
174
 * @return -1 in case of error, when pointer to connection does not get initialized, 0 if OK
175
 */
176
int ulEventHttpClientSetup(const char *address, unsigned short port, struct evhttp_connection **htc);
177

    
178
/**
179
 * Post a block of data via http to a remote application.
180
 *
181
 * Performs a POST http request operation towards a remote http server in order to transfer a bulk
182
 * block of bytes to the server entity through the already establised connection.
183
 *
184
 * @param data A pointer to the block of bytes to be transferred
185
 * @param data_len The length of the data block
186
 * @param htc A pointer to the already established libevent-based http connection to the server
187
 * @param path The path within the remote application to push data to
188
 * @return -1 in case of error, or when pointer to connection does not get initialized, 0 if OK
189
 */
190
int ulEventHttpClientPostData(uint8_t *data, unsigned int data_len, struct evhttp_connection *htc, const char *addr, const int port, const char *path);
191

    
192

    
193
//DOCUMENTATION RELATIVE TO THE RECEIVERS_REGISTRY.C FILE
194
/**
195
 * Register a new receiver application.
196
 *
197
 * The remote application registers itself by declaring something
198
 * like "http://address:port/path/to/receiver/"
199
 * The function can be used to retrieve information about an already registered
200
 * application at a specific position, by giving NULL inputs except
201
 * for the pos parameter.
202
 *
203
 * @param[in,out] address The application IP address
204
 * @param[in,out] port The application port
205
 * @param[in,out] path The path where to send chunks
206
 * @param[in,out] pos The position in the registration array
207
 * @return 0 if OK, -1 if problems
208
 */
209
int ulRegisterApplication(char *address, int *port, char* path, int *pos);
210

    
211

    
212
#endif        /* CHUNK_EXTERNAL_INTERFACE_H */