LGPL
[vlc.git] / include / vlc_access.h
1 /*****************************************************************************
2  * vlc_access.h: Access descriptor, queries and methods
3  *****************************************************************************
4  * Copyright (C) 1999-2006 VLC authors and VideoLAN
5  * $Id$
6  *
7  * Authors: Laurent Aimar <fenrir@via.ecp.fr>
8  *
9  * This program is free software; you can redistribute it and/or modify it
10  * under the terms of the GNU Lesser General Public License as published by
11  * the Free Software Foundation; either version 2.1 of the License, or
12  * (at your option) any later version.
13  *
14  * This program is distributed in the hope that it will be useful,
15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17  * GNU Lesser General Public License for more details.
18  *
19  * You should have received a copy of the GNU Lesser General Public License
20  * along with this program; if not, write to the Free Software Foundation,
21  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
22  *****************************************************************************/
23
24 #ifndef VLC_ACCESS_H
25 #define VLC_ACCESS_H 1
26
27 /**
28  * \file
29  * This file defines functions and definitions for access object
30  */
31
32 #include <vlc_block.h>
33
34 /**
35  * \defgroup access Access
36  * @{
37  */
38
39 enum access_query_e
40 {
41     /* capabilities */
42     ACCESS_CAN_SEEK,        /* arg1= bool*    cannot fail */
43     ACCESS_CAN_FASTSEEK,    /* arg1= bool*    cannot fail */
44     ACCESS_CAN_PAUSE,       /* arg1= bool*    cannot fail */
45     ACCESS_CAN_CONTROL_PACE,/* arg1= bool*    cannot fail */
46
47     /* */
48     ACCESS_GET_PTS_DELAY = 0x101,/* arg1= int64_t*       cannot fail */
49     /* */
50     ACCESS_GET_TITLE_INFO,  /* arg1=input_title_t*** arg2=int*      res=can fail */
51     /* Meta data */
52     ACCESS_GET_META,        /* arg1= vlc_meta_t **                  res=can fail */
53
54     /* */
55     ACCESS_GET_CONTENT_TYPE,/* arg1=char **ppsz_content_type                       res=can fail */
56
57     /* */
58     ACCESS_GET_SIGNAL,      /* arg1=double *pf_quality, arg2=double *pf_strength   res=can fail */
59
60     /* */
61     ACCESS_SET_PAUSE_STATE = 0x200, /* arg1= bool           can fail */
62
63     /* */
64     ACCESS_SET_TITLE,       /* arg1= int            can fail */
65     ACCESS_SET_SEEKPOINT,   /* arg1= int            can fail */
66
67     /* Special mode for access/demux communication
68      * XXX: avoid to use it unless you can't */
69     ACCESS_SET_PRIVATE_ID_STATE = 0x1000, /* arg1= int i_private_data, bool b_selected    res=can fail */
70     ACCESS_SET_PRIVATE_ID_CA,             /* arg1= int i_program_number, uint16_t i_vpid, uint16_t i_apid1, uint16_t i_apid2, uint16_t i_apid3, uint8_t i_length, uint8_t *p_data */
71     ACCESS_GET_PRIVATE_ID_STATE,          /* arg1=int i_private_data arg2=bool *          res=can fail */
72 };
73
74 struct access_t
75 {
76     VLC_COMMON_MEMBERS
77
78     /* Module properties */
79     module_t    *p_module;
80
81     /* Access name (empty if non forced) */
82     char        *psz_access;
83     char        *psz_location; /**< Location (URL with the scheme stripped) */
84     char        *psz_filepath; /**< Local file path (if applicable) */
85
86     /* Access can fill this entry to force a demuxer
87      * XXX: fill it once you know for sure you will succeed
88      * (if you fail, this value won't be reseted */
89     char        *psz_demux;
90
91     /* pf_read/pf_block is used to read data.
92      * XXX A access should set one and only one of them */
93     ssize_t     (*pf_read) ( access_t *, uint8_t *, size_t );  /* Return -1 if no data yet, 0 if no more data, else real data read */
94     block_t    *(*pf_block)( access_t * );                  /* return a block of data in his 'natural' size, NULL if not yet data or eof */
95
96     /* Called for each seek.
97      * XXX can be null */
98     int         (*pf_seek) ( access_t *, uint64_t );         /* can be null if can't seek */
99
100     /* Used to retreive and configure the access
101      * XXX mandatory. look at access_query_e to know what query you *have to* support */
102     int         (*pf_control)( access_t *, int i_query, va_list args);
103
104     /* Access has to maintain them uptodate */
105     struct
106     {
107         unsigned int i_update;  /* Access sets them on change,
108                                    Input removes them once take into account*/
109
110         uint64_t     i_size;    /* Write only for access, read only for input */
111         uint64_t     i_pos;     /* idem */
112         bool         b_eof;     /* idem */
113
114         int          i_title;    /* idem, start from 0 (could be menu) */
115         int          i_seekpoint;/* idem, start from 0 */
116     } info;
117     access_sys_t *p_sys;
118
119     /* Weak link to parent input */
120     input_thread_t *p_input;
121 };
122
123 static inline int access_vaControl( access_t *p_access, int i_query, va_list args )
124 {
125     if( !p_access ) return VLC_EGENERIC;
126     return p_access->pf_control( p_access, i_query, args );
127 }
128
129 static inline int access_Control( access_t *p_access, int i_query, ... )
130 {
131     va_list args;
132     int     i_result;
133
134     va_start( args, i_query );
135     i_result = access_vaControl( p_access, i_query, args );
136     va_end( args );
137     return i_result;
138 }
139
140 static inline void access_InitFields( access_t *p_a )
141 {
142     p_a->info.i_update = 0;
143     p_a->info.i_size = 0;
144     p_a->info.i_pos = 0;
145     p_a->info.b_eof = false;
146     p_a->info.i_title = 0;
147     p_a->info.i_seekpoint = 0;
148 }
149
150 /**
151  * This function will return the parent input of this access.
152  * It is retained. It can return NULL.
153  */
154 VLC_API input_thread_t * access_GetParentInput( access_t *p_access ) VLC_USED;
155
156 #define ACCESS_SET_CALLBACKS( read, block, control, seek ) \
157     do { \
158         p_access->pf_read = (read); \
159         p_access->pf_block = (block); \
160         p_access->pf_control = (control); \
161         p_access->pf_seek = (seek); \
162     } while(0)
163
164 #define STANDARD_READ_ACCESS_INIT \
165     do { \
166         access_InitFields( p_access ); \
167         ACCESS_SET_CALLBACKS( Read, NULL, Control, Seek ); \
168         p_sys = p_access->p_sys = calloc( 1, sizeof( access_sys_t ) ); \
169         if( !p_sys ) return VLC_ENOMEM;\
170     } while(0);
171
172 #define STANDARD_BLOCK_ACCESS_INIT \
173     do { \
174         access_InitFields( p_access ); \
175         ACCESS_SET_CALLBACKS( NULL, Block, Control, Seek ); \
176         p_sys = p_access->p_sys = calloc( 1, sizeof( access_sys_t ) ); \
177         if( !p_sys ) return VLC_ENOMEM; \
178     } while(0);
179
180 /**
181  * @}
182  */
183
184 #endif