Difference between revisions of "Hacker Guide/Access"

From VideoLAN Wiki
Jump to navigation Jump to search
Line 1: Line 1:
 
== Description  ==
 
== Description  ==
  
The modules of ''''access'''' capability are designed to be the first and last elements of a modules chain.
+
The modules of ''''access'''' capability are designed to be the first and last elements of a modules chain.  
  
Access [[Documentation:Hacker's Guide/Access|input]] and [[Documentation:Hacker's Guide/Access output|output]] handles most of the basic '''I/O''' for VLC. They are usually '''protocols''' implementations (http, ftp,...) or '''devices''' access (Webcams, Capture cards).
+
Access [[Documentation:Hacker's Guide/Access|input]] and [[Documentation:Hacker's Guide/Access output|output]] handles most of the basic '''I/O''' for VLC. They are usually '''protocols''' implementations (http, ftp,...) or '''devices''' access (Webcams, Capture cards).  
  
We will discuss about ''''input access'''' in this page.
+
We will discuss about ''''input access'''' in this page.  
  
== Starting to write an access module ==
+
== Starting to write an access module ==
  
To write an access module, read the [[Documentation:Hacker's_Guide/Module_Writers_Guide|introduction to module writing]].
+
To write an access module, read the [[Documentation:Hacker's Guide/Module Writers Guide|introduction to module writing]].  
 +
 
 +
Then, you should specify your module of being of access type:
  
Then, you should specify your module of being of access type:
 
 
  set_capability( "access", 60 )   
 
  set_capability( "access", 60 )   
 
  set_category( CAT_INPUT )                                                                                                                                                                                   
 
  set_category( CAT_INPUT )                                                                                                                                                                                   
 
  set_subcategory( SUBCAT_INPUT_ACCESS )
 
  set_subcategory( SUBCAT_INPUT_ACCESS )
  
Your module can be of either a ''''Block'''' or a ''''Read'''' type, depending on what you need to access.
+
Your module can be of either a ''''Block'''' or a ''''Read'''' type, depending on what you need to access.
 +
 
 +
== Functions to implement  ==
 +
 
 +
After implementing Open() and Close() functions, you will need to implement a few majors features that will be implemented by your functions.  
  
== Functions to implement ==
+
As you can see {{VLCSourceFile|name=include/vlc_access.h}}, you should define:
  
After implementing Open() and Close() functions, you will need to implement a few majors features that will be implemented by your functions.
+
*Seek, as in pf_seek  
+
*Control, as in pf_control  
As you can see {{VLCSourceFile|name=include/vlc_access.h}}, you should define:
+
*Read or Block, depending on your module type
* Seek, as in pf_seek
 
* Control, as in pf_control
 
* Read or Block
 
  
After implementing those functions, you should assign them to the corresponding pf_ function.
+
After implementing those functions, you should assign them to the corresponding pf_ function.  
 +
 
 +
== Seek  ==
 +
 
 +
''Prototype'':
  
== Seek ==
 
''Prototype'':
 
 
  int        (*pf_seek) ( access_t *, uint64_t );
 
  int        (*pf_seek) ( access_t *, uint64_t );
  
The seeking function will be called whenever a seek is requested.
+
The seeking function will be called whenever a seek is requested.  
  
 
The arguments are a ''pointer'' to the module structure, and the requested '''position'''.  
 
The arguments are a ''pointer'' to the module structure, and the requested '''position'''.  
  
'''NB:''' Seeking function can be NULL, if it isn't possible to seek in the protocol or device.
+
'''NB:''' Seeking function can be NULL, if it isn't possible to seek in the protocol or device.  
 +
 
 +
''Return:''<br>
 +
 
 +
If the seek has succeeded, it should return VLC_SUCCESS, else it should return VLC_EGENERIC. <br>
 +
 
 +
== Control  ==
 +
 
 +
''Prototype'':
  
== Control ==
 
''Prototype'':
 
 
  int        (*pf_control)( access_t *, int i_query, va_list args);
 
  int        (*pf_control)( access_t *, int i_query, va_list args);
  
Control function is quite easy, the input core will query the module using this function.
+
Control function is quite easy, the input core will query the module using this function.
 +
 
 +
The '''i_query''' parameter can be of several type. We will cover here the most important ones.  
  
The '''i_query''' parameter can be of several type. We will cover here the most important ones.
+
''Return'':
  
''Return'':
+
If the query has succeeded, it should return VLC_SUCCESS. Else it should return VLC_EGENERIC (''fail'').
  
If the query has succeeded, it should return VLC_SUCCESS. Else it should return VLC_EGENERIC.
+
=== Control Query types  ===
  
=== Control Query types ===
+
The first ones are request to know what the module supports. They are all of '''boolean''' type and should always succeed.
  
The first ones are request to know what the module supports. They are all of '''boolean''' type and should always succeed.
 
 
  ACCESS_CAN_SEEK,         
 
  ACCESS_CAN_SEEK,         
 
  ACCESS_CAN_FASTSEEK,     
 
  ACCESS_CAN_FASTSEEK,     
Line 59: Line 70:
 
  ACCESS_CAN_CONTROL_PACE,
 
  ACCESS_CAN_CONTROL_PACE,
  
 +
<br> The following one is a request for the '''PTS delay'''. It must always succeed.
  
The following one is a request for the '''PTS delay'''. It must always succeed.
 
 
  ACCESS_GET_PTS_DELAY,
 
  ACCESS_GET_PTS_DELAY,
  
 +
<br> The following ones are for '''requesting''' various '''info''' about the input, like Metadata, Titles and Chapters or device signal strength. All of them can fail.
  
The following ones are for '''requesting''' various '''info''' about the input, like Metadata, Titles and Chapters or device signal strength. All of them can fail.
 
 
  ACCESS_GET_TITLE_INFO,   
 
  ACCESS_GET_TITLE_INFO,   
 
  ACCESS_GET_META,         
 
  ACCESS_GET_META,         
Line 70: Line 81:
 
  ACCESS_GET_SIGNAL,       
 
  ACCESS_GET_SIGNAL,       
  
 +
<br> Depending to the answer of the CAN_ requests, the core can '''set''' a few things, like pausing or changing '''title''' or '''chapter'''
  
Depending to the answer of the CAN_ requests, the core can '''set''' a few things, like pausing or changing '''title''' or '''chapter'''
 
 
  ACCESS_SET_PAUSE_STATE,
 
  ACCESS_SET_PAUSE_STATE,
 
  ACCESS_SET_TITLE,
 
  ACCESS_SET_TITLE,
 
  ACCESS_SET_SEEKPOINT,
 
  ACCESS_SET_SEEKPOINT,
  
== Read ==
+
== Read ==
''Prototype'':
+
 
 +
''Prototype'':  
 +
 
 
  ssize_t    (*pf_read) ( access_t *, uint8_t *, size_t );
 
  ssize_t    (*pf_read) ( access_t *, uint8_t *, size_t );
  
''Return'':
+
''Return'':  
 +
 
 +
Return -1 if no data yet, 0 if no more data, else actual data read on the medium.
 +
 
 +
== Block  ==
  
Return -1 if no data yet, 0 if no more data, else actual data read on the medium.
+
''Prototype'':
  
== Block ==
 
''Prototype'':
 
 
  block_t    *(*pf_block)( access_t * );
 
  block_t    *(*pf_block)( access_t * );
  
''Return:''
+
''Return:''  
  
 
Returns a block of data in his 'natural' size. It will return NULL if not yet data or eof.
 
Returns a block of data in his 'natural' size. It will return NULL if not yet data or eof.

Revision as of 16:40, 11 November 2010

Description

The modules of 'access' capability are designed to be the first and last elements of a modules chain.

Access input and output handles most of the basic I/O for VLC. They are usually protocols implementations (http, ftp,...) or devices access (Webcams, Capture cards).

We will discuss about 'input access' in this page.

Starting to write an access module

To write an access module, read the introduction to module writing.

Then, you should specify your module of being of access type:

set_capability( "access", 60 )  
set_category( CAT_INPUT )                                                                                                                                                                                  
set_subcategory( SUBCAT_INPUT_ACCESS )

Your module can be of either a 'Block' or a 'Read' type, depending on what you need to access.

Functions to implement

After implementing Open() and Close() functions, you will need to implement a few majors features that will be implemented by your functions.

As you can see include/vlc_access.h, you should define:

  • Seek, as in pf_seek
  • Control, as in pf_control
  • Read or Block, depending on your module type

After implementing those functions, you should assign them to the corresponding pf_ function.

Seek

Prototype:

int         (*pf_seek) ( access_t *, uint64_t );

The seeking function will be called whenever a seek is requested.

The arguments are a pointer to the module structure, and the requested position.

NB: Seeking function can be NULL, if it isn't possible to seek in the protocol or device.

Return:

If the seek has succeeded, it should return VLC_SUCCESS, else it should return VLC_EGENERIC.

Control

Prototype:

int         (*pf_control)( access_t *, int i_query, va_list args);

Control function is quite easy, the input core will query the module using this function.

The i_query parameter can be of several type. We will cover here the most important ones.

Return:

If the query has succeeded, it should return VLC_SUCCESS. Else it should return VLC_EGENERIC (fail).

Control Query types

The first ones are request to know what the module supports. They are all of boolean type and should always succeed.

ACCESS_CAN_SEEK,        
ACCESS_CAN_FASTSEEK,    
ACCESS_CAN_PAUSE,       
ACCESS_CAN_CONTROL_PACE,


The following one is a request for the PTS delay. It must always succeed.

ACCESS_GET_PTS_DELAY,


The following ones are for requesting various info about the input, like Metadata, Titles and Chapters or device signal strength. All of them can fail.

ACCESS_GET_TITLE_INFO,  
ACCESS_GET_META,        
ACCESS_GET_CONTENT_TYPE,
ACCESS_GET_SIGNAL,      


Depending to the answer of the CAN_ requests, the core can set a few things, like pausing or changing title or chapter

ACCESS_SET_PAUSE_STATE,
ACCESS_SET_TITLE,
ACCESS_SET_SEEKPOINT,

Read

Prototype:

ssize_t     (*pf_read) ( access_t *, uint8_t *, size_t );

Return:

Return -1 if no data yet, 0 if no more data, else actual data read on the medium.

Block

Prototype:

block_t    *(*pf_block)( access_t * );

Return:

Returns a block of data in his 'natural' size. It will return NULL if not yet data or eof.