Difference between revisions of "Hacker Guide/Access"

From VideoLAN Wiki
Jump to navigation Jump to search
(Format, copy-edit)
 
(43 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 +
{{Back to|Hacker Guide}}
 
== 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).
+
They take an [[MRL]] in, and output a bitstream, that can be fed to a [[Demuxer]].
 +
 
 +
Access input and [[{{#rel2abs:../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 ==
+
== 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 first the [[{{#rel2abs:../How To Write a Module}}|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:  
 +
<syntaxhighlight lang="c">
 
  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 )
 +
</syntaxhighlight>
 +
 +
=== Type ===
 +
Your module can be of either a ''''Block'''' or a ''''Read'''' type, depending on your medium:
 +
 +
* if the underlying protocol '''returns data blocks of unknown or unpredictable size''', '''Block''' is a better type,
 +
* if you '''can control the size of the data requested''' to the underlying protocol, '''Read''' is a better type.
  
−
== Functions to implement ==
+
== 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.
+
After implementing <code>Open()</code> and <code>Close()</code> functions, you will need to implement a few major features that will be implemented by your functions.  
−
 
−
As you can see {{VLCSourceFile|name=include/vlc_access.h}}, you should define:
 
−
* Seek, as in pf_seek
 
−
* Control, as in pf_control
 
−
* Read or Block
 
  
−
Your module can be of a ''''Block'''' or a ''''Read'''' type, depending on what you need to access.
+
As you can see in [https://www.videolan.org/developers/vlc/doc/doxygen/html/vlc__access_8h_source.html include/vlc_access.h], you should define:
  
−
After implementing those function, you should assign them to the corresponding pf_ function.
+
* Seek, as in <code>pf_seek</code>,
 +
* Control, as in <code>pf_control</code>,
 +
* Read or Block, depending on your module [[#Type|type]].
  
−
== Seek ==
+
After implementing those functions, you should assign them to the corresponding <code>pf_</code> function.
−
''Prototype'':
+
 
 +
=== Seek ===
 +
 
 +
''Prototype'':  
 +
<syntaxhighlight lang="c">
 
  int        (*pf_seek) ( access_t *, uint64_t );
 
  int        (*pf_seek) ( access_t *, uint64_t );
 +
</syntaxhighlight>
  
−
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.
+
{{Note-nb|Seeking function can be <code>NULL</code>, if it isn't possible to seek in the protocol or device.}}
  
−
== Control ==
+
You shall set <code>p_access->info.b_eof</code> to <code>false</code> if seek worked.
 +
 
 +
''Return:''<br>
 +
 
 +
If the seek has succeeded, it should return <code>VLC_SUCCESS</code>, else it should return <code>VLC_EGENERIC</code>. <br>
 +
 
 +
=== Control ===
 +
 
 +
''Prototype'':
 +
<syntaxhighlight lang="c">
 
  int        (*pf_control)( access_t *, int i_query, va_list args);
 
  int        (*pf_control)( access_t *, int i_query, va_list args);
 +
</syntaxhighlight>
 +
 +
Control function is quite easy, the input core will query the module using this function with:
 +
 +
*A pointer to the module structure.
 +
*An '''i_query''' parameter that can be of several type. We will cover afterward the most important on.
 +
*A list of arguments, that depends on the '''i_query''' type.
 +
 +
 +
''Return'':
 +
 +
If the query has succeeded, it should return <code>VLC_SUCCESS</code>. Else it should return <code>VLC_EGENERIC</code> (''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.
 +
<syntaxhighlight lang="c">
 +
ACCESS_CAN_SEEK,       
 +
ACCESS_CAN_FASTSEEK,   
 +
ACCESS_CAN_PAUSE,     
 +
ACCESS_CAN_CONTROL_PACE,
 +
</syntaxhighlight>
 +
 +
<br> The following one is a request for the '''PTS delay'''. It must always succeed.
 +
<syntaxhighlight lang="c">
 +
ACCESS_GET_PTS_DELAY,
 +
</syntaxhighlight>
 +
 +
<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.
 +
<syntaxhighlight lang="c">
 +
ACCESS_GET_TITLE_INFO, 
 +
ACCESS_GET_META,       
 +
ACCESS_GET_CONTENT_TYPE,
 +
ACCESS_GET_SIGNAL,     
 +
</syntaxhighlight>
 +
 +
<br> Depending to the answer of the <code>CAN_</code> requests, the core can '''set''' a few things, like pausing or changing '''title''' or '''chapter'''
 +
<syntaxhighlight lang="c">
 +
ACCESS_SET_PAUSE_STATE,
 +
ACCESS_SET_TITLE,
 +
ACCESS_SET_SEEKPOINT,
 +
</syntaxhighlight>
 +
 +
You can find the list of arguments corresponding to query types in the comments of <code>access_query_e</code> definition in vlc_access.h
 +
 +
=== Read  ===
 +
 +
''Prototype'':
 +
<syntaxhighlight lang="c">
 +
ssize_t    (*pf_read) ( access_t *, uint8_t *, size_t );
 +
</syntaxhighlight>
 +
 +
''Return'':
 +
 +
Return <code>-1</code> if no data yet, <code>0</code> if no more data, else actual data read on the medium.
 +
 +
=== Block  ===
  
−
== Read ==
+
''Prototype'':
−
  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 */
+
<syntaxhighlight lang="c">
 +
  block_t    *(*pf_block)( access_t * );
 +
</syntaxhighlight>
  
−
== Block ==
+
''Return:''
−
block_t    *(*pf_block)( access_t * );                  /* return a block of data in his 'natural' size, NULL if not yet data or eof */
 
  
−
== Functionality  ==
+
Returns a block of data in its 'natural' size. It will return <code>NULL</code> if there is not yet data or end-of-file (eof) has been reached.
  
−
Generally speaking, [[Documentation:Hacker's Guide/Access|access input]] will provide Read() functions and [[Documentation:Hacker's Guide/Access output|output]] Write().  
+
To differentiate between ''no data'' and ''eof'', you shall set <code>p_access->info.b_eof</code> to <code>true</code> in case of eof.
  
−
Both needs to provide Seek() and Control() even if the underlying architecture does not support these actions. In this case, Seek() and Control() should return VLC_EGENERIC, although Control() might need to answer ACCESS_OUT_CONTROLS_PACE requests. See modules/access_output/http.c about using a source without seeking.
+
{{Hacker_Guide}}

Latest revision as of 05:23, 25 April 2019

← Back to Hacker Guide

Description

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

They take an MRL in, and output a bitstream, that can be fed to a Demuxer.

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.

Write an access module

To write an access module, read first 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 )

Type

Your module can be of either a 'Block' or a 'Read' type, depending on your medium:

  • if the underlying protocol returns data blocks of unknown or unpredictable size, Block is a better type,
  • if you can control the size of the data requested to the underlying protocol, Read is a better type.

Functions to implement

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

As you can see in 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.

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

You shall set p_access->info.b_eof to false if seek worked.

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 with:

  • A pointer to the module structure.
  • An i_query parameter that can be of several type. We will cover afterward the most important on.
  • A list of arguments, that depends on the i_query type.


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,

You can find the list of arguments corresponding to query types in the comments of access_query_e definition in vlc_access.h

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 its 'natural' size. It will return NULL if there is not yet data or end-of-file (eof) has been reached.

To differentiate between no data and eof, you shall set p_access->info.b_eof to true in case of eof.

This page is part of official VLC media player Documentation (User Guide • Streaming HowTo • Hacker Guide • Modules)
Please read the Documentation Editing Guidelines before you edit the documentation
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
Retrieved from "https://wiki.videolan.org/index.php?title=Hacker_Guide/Access&oldid=61268"