* ninput : a little developer documentation.

include/ninput.h

@@ -2,7 +2,7 @@
  * ninput.h
  *****************************************************************************
  * Copyright (C) 1999-2001 VideoLAN
- * $Id: ninput.h,v 1.2 2003/08/02 16:43:59 fenrir Exp $
+ * $Id: ninput.h,v 1.3 2003/08/02 19:16:04 fenrir Exp $
  *
  * Authors: Laurent Aimar <fenrir@via.ecp.fr>
  *
@@ -25,10 +25,44 @@
 #define _NINPUT_H 1
 
 /*
- * Stream
+ * Stream (stream_t)
+ * -----------------
+ *  This will allow you to easily handle read/seek in demuxer modules.
  *
+ * - stream_OpenInput
+ *      create a "stream_t *" from an "input_thread_t *".
+ * - stream_Release
+ *      destroy a previously "stream_t *" instances.
+ * - stream_Read
+ *      Try to read "i_read" bytes into a buffer pointed by "p_read".
+ *      If "p_read" is NULL then data are skipped instead of read.
+ *      The return value is the real numbers of bytes read/skip. If
+ *      this value is less than i_read that means that it's the end
+ *      of the stream.
+ * - stream_Peek
+ *      Store in pp_peek a pointer to the next "i_peek" bytes in the
+ *      stream
+ *      The return value is the real numbers of valid bytes, if it's
+ *      less or equal to 0, *pp_peek is invalid.
+ *      XXX: it's a pointer to internal buffer and it will be invalid
+ *      as soons as other stream_* functions are called.
+ *      be 0 (then *pp_peek isn't valid).
+ *      XXX: due to input limitation, it could be less than i_peek without
+ *      meaning the end of the stream (but only when you have
+ *      i_peek >= p_input->i_bufsize)
+ * - stream_PesPacket
+ *      Read "i_size" bytes and store them in a pes_packet_t.
+ *      Only fields p_first, p_last, i_nb_data, and i_pes_size are set.
+ *      (Of course, you need to fill i_dts, i_pts, ... )
+ *      If only less than "i_size" bytes are available NULL is returned.
+ * - stream_vaControl, stream_Control
+ *      Use to control the "stream_t *". Look at stream_query_e for possible
+ *      "i_query" value and format arguments.
+ *      Return VLC_SUCCESS if ... succeed ;) and VLC_EGENERIC if failed or
+ *      unimplemented
  */
-enum streamQuery_e
+
+enum stream_query_e
 {
     /* capabilities */
     STREAM_CAN_SEEK,            /* arg1= vlc_bool_t *   res=cannot fail*/
@@ -43,10 +77,10 @@ enum streamQuery_e
 
 /*
  * Demux
- *
+ * XXX: don't look at it yet.
  */
 #define DEMUX_POSITION_MAX  10000
-enum demuxQuery_e
+enum demux_query_e
 {
     DEMUX_GET_POSITION,         /* arg1= int64_t *      res=    */
     DEMUX_SET_POSITION,         /* arg1= int64_t        res=can fail    */
@@ -58,17 +92,18 @@ enum demuxQuery_e
 };
 
 
+/* Stream */
 VLC_EXPORT( stream_t *,     stream_OpenInput,       ( input_thread_t * ) );
 VLC_EXPORT( void,           stream_Release,         ( stream_t * ) );
-VLC_EXPORT( int,            stream_vaControl,       ( stream_t *, int, va_list ) );
-VLC_EXPORT( int,            stream_Control,         ( stream_t *, int, ... ) );
-VLC_EXPORT( int,            stream_Read,            ( stream_t *, void *, int ) );
-VLC_EXPORT( int,            stream_Peek,            ( stream_t *, uint8_t **, int ) );
-
-VLC_EXPORT( pes_packet_t *, stream_PesPacket,       ( stream_t *, int ) );
+VLC_EXPORT( int,            stream_vaControl,       ( stream_t *, int i_query, va_list ) );
+VLC_EXPORT( int,            stream_Control,         ( stream_t *, int i_query, ... ) );
+VLC_EXPORT( int,            stream_Read,            ( stream_t *, void *p_read, int i_read ) );
+VLC_EXPORT( int,            stream_Peek,            ( stream_t *, uint8_t **pp_peek, int i_peek ) );
+VLC_EXPORT( pes_packet_t *, stream_PesPacket,       ( stream_t *, int i_size ) );
 
-VLC_EXPORT( int,            demux_vaControl,        ( input_thread_t *, int, va_list  ) );
-VLC_EXPORT( int,            demux_Control,          ( input_thread_t *, int, ...  ) );
+/* Demux */
+VLC_EXPORT( int,            demux_vaControl,        ( input_thread_t *, int i_query, va_list  ) );
+VLC_EXPORT( int,            demux_Control,          ( input_thread_t *, int i_query, ...  ) );
 
 #endif