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

After implementing those function, 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.

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

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