View source for Hacker Guide/Access

== Description  ==

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).

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

== Starting to write an access module ==

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:
 set_capability( "access", 60 )  
 set_category( CAT_INPUT )                                                                                                                                                                                  
 set_subcategory( SUBCAT_INPUT_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 {{VLCSourceFile|name=include/vlc_access.h}}, you should define:
 * Seek
 * Control
 * Read or Block

=== ===

int         (*pf_seek) ( access_t *, uint64_t );         /* can be null if can't seek */
  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);

== Functionality  ==

Generally speaking, [[Documentation:Hacker's Guide/Access|access input]] will provide Read() functions and [[Documentation:Hacker's Guide/Access output|output]] Write(). 

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.