Improve source/stream terminology consistency
authorTimothy B. Terriberry <tterribe@xiph.org>
Fri, 7 Jul 2017 21:36:18 +0000 (14:36 -0700)
committerTimothy B. Terriberry <tterribe@xiph.org>
Fri, 7 Jul 2017 23:04:50 +0000 (16:04 -0700)
We inherited the term "source" from vorbisfile's "datasource", but
 were using it interchangeably with stream.
At least one user did not even realize the that the _source
 parameter passed to op_open_callbacks() was the same as the
 _stream parameter taken by those callbacks, which is reasonable
 because we never said so.
Consistently use "stream" instead of "source" in both the
 documentation and the code.

include/opusfile.h
src/internal.h
src/opusfile.c

index 5047637..e3a3dc8 100644 (file)
@@ -1155,16 +1155,18 @@ OP_WARN_UNUSED_RESULT OggOpusFile *op_open_url(const char *_url,
  int *_error,...) OP_ARG_NONNULL(1);
 
 /**Open a stream using the given set of callbacks to access it.
-   \param _source        The stream to read from (e.g., a <code>FILE *</code>).
+   \param _stream        The stream to read from (e.g., a <code>FILE *</code>).
+                         This value will be passed verbatim as the first
+                          argument to all of the callbacks.
    \param _cb            The callbacks with which to access the stream.
                          <code><a href="#op_read_func">read()</a></code> must
                           be implemented.
                          <code><a href="#op_seek_func">seek()</a></code> and
                           <code><a href="#op_tell_func">tell()</a></code> may
                           be <code>NULL</code>, or may always return -1 to
-                          indicate a source is unseekable, but if
+                          indicate a stream is unseekable, but if
                           <code><a href="#op_seek_func">seek()</a></code> is
-                          implemented and succeeds on a particular source, then
+                          implemented and succeeds on a particular stream, then
                           <code><a href="#op_tell_func">tell()</a></code> must
                           also.
                          <code><a href="#op_close_func">close()</a></code> may
@@ -1227,11 +1229,11 @@ OP_WARN_UNUSED_RESULT OggOpusFile *op_open_url(const char *_url,
                             basic validity checks.</dd>
                          </dl>
    \return A freshly opened \c OggOpusFile, or <code>NULL</code> on error.
-           <tt>libopusfile</tt> does <em>not</em> take ownership of the source
+           <tt>libopusfile</tt> does <em>not</em> take ownership of the stream
             if the call fails.
-           The calling application is responsible for closing the source if
+           The calling application is responsible for closing the stream if
             this call returns an error.*/
-OP_WARN_UNUSED_RESULT OggOpusFile *op_open_callbacks(void *_source,
+OP_WARN_UNUSED_RESULT OggOpusFile *op_open_callbacks(void *_stream,
  const OpusFileCallbacks *_cb,const unsigned char *_initial_data,
  size_t _initial_bytes,int *_error) OP_ARG_NONNULL(2);
 
@@ -1333,18 +1335,20 @@ OP_WARN_UNUSED_RESULT OggOpusFile *op_test_url(const char *_url,
    For new code, you are likely better off using op_test() instead, which
     is less resource-intensive, requires less data to succeed, and imposes a
     hard limit on the amount of data it examines (important for unseekable
-    sources, where all such data must be buffered until you are sure of the
+    streams, where all such data must be buffered until you are sure of the
     stream type).
-   \param _source        The stream to read from (e.g., a <code>FILE *</code>).
+   \param _stream        The stream to read from (e.g., a <code>FILE *</code>).
+                         This value will be passed verbatim as the first
+                          argument to all of the callbacks.
    \param _cb            The callbacks with which to access the stream.
                          <code><a href="#op_read_func">read()</a></code> must
                           be implemented.
                          <code><a href="#op_seek_func">seek()</a></code> and
                           <code><a href="#op_tell_func">tell()</a></code> may
                           be <code>NULL</code>, or may always return -1 to
-                          indicate a source is unseekable, but if
+                          indicate a stream is unseekable, but if
                           <code><a href="#op_seek_func">seek()</a></code> is
-                          implemented and succeeds on a particular source, then
+                          implemented and succeeds on a particular stream, then
                           <code><a href="#op_tell_func">tell()</a></code> must
                           also.
                          <code><a href="#op_close_func">close()</a></code> may
@@ -1374,11 +1378,11 @@ OP_WARN_UNUSED_RESULT OggOpusFile *op_test_url(const char *_url,
                          See op_open_callbacks() for a full list of failure
                           codes.
    \return A partially opened \c OggOpusFile, or <code>NULL</code> on error.
-           <tt>libopusfile</tt> does <em>not</em> take ownership of the source
+           <tt>libopusfile</tt> does <em>not</em> take ownership of the stream
             if the call fails.
-           The calling application is responsible for closing the source if
+           The calling application is responsible for closing the stream if
             this call returns an error.*/
-OP_WARN_UNUSED_RESULT OggOpusFile *op_test_callbacks(void *_source,
+OP_WARN_UNUSED_RESULT OggOpusFile *op_test_callbacks(void *_stream,
  const OpusFileCallbacks *_cb,const unsigned char *_initial_data,
  size_t _initial_bytes,int *_error) OP_ARG_NONNULL(2);
 
@@ -1435,7 +1439,7 @@ void op_free(OggOpusFile *_of);
    Their documention will indicate so explicitly.*/
 /*@{*/
 
-/**Returns whether or not the data source being read is seekable.
+/**Returns whether or not the stream being read is seekable.
    This is true if
    <ol>
    <li>The <code><a href="#op_seek_func">seek()</a></code> and
@@ -1456,9 +1460,9 @@ int op_seekable(const OggOpusFile *_of) OP_ARG_NONNULL(1);
     return 1.
    The actual number of links is not known until the stream is fully opened.
    \param _of The \c OggOpusFile from which to retrieve the link count.
-   \return For fully-open seekable sources, this returns the total number of
+   \return For fully-open seekable streams, this returns the total number of
             links in the whole stream, which will be at least 1.
-           For partially-open or unseekable sources, this always returns 1.*/
+           For partially-open or unseekable streams, this always returns 1.*/
 int op_link_count(const OggOpusFile *_of) OP_ARG_NONNULL(1);
 
 /**Get the serial number of the given link in a (possibly-chained) Ogg Opus
@@ -1472,7 +1476,7 @@ int op_link_count(const OggOpusFile *_of) OP_ARG_NONNULL(1);
    \return The serial number of the given link.
            If \a _li is greater than the total number of links, this returns
             the serial number of the last link.
-           If the source is not seekable, this always returns the serial number
+           If the stream is not seekable, this always returns the serial number
             of the current link.*/
 opus_uint32 op_serialno(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
 
@@ -1489,7 +1493,7 @@ opus_uint32 op_serialno(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
    \return The channel count of the given link.
            If \a _li is greater than the total number of links, this returns
             the channel count of the last link.
-           If the source is not seekable, this always returns the channel count
+           If the stream is not seekable, this always returns the channel count
             of the current link.*/
 int op_channel_count(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
 
@@ -1508,9 +1512,9 @@ int op_channel_count(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
             compressed size of link \a _li if it is non-negative, or a negative
             value on error.
            The compressed size of the entire stream may be smaller than that
-            of the underlying source if trailing garbage was detected in the
+            of the underlying stream if trailing garbage was detected in the
             file.
-   \retval #OP_EINVAL The source is not seekable (so we can't know the length),
+   \retval #OP_EINVAL The stream is not seekable (so we can't know the length),
                        \a _li wasn't less than the total number of links in
                        the stream, or the stream was only partially open.*/
 opus_int64 op_raw_total(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
@@ -1528,7 +1532,7 @@ opus_int64 op_raw_total(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
    \return The PCM length of the entire stream if \a _li is negative, the PCM
             length of link \a _li if it is non-negative, or a negative value on
             error.
-   \retval #OP_EINVAL The source is not seekable (so we can't know the length),
+   \retval #OP_EINVAL The stream is not seekable (so we can't know the length),
                        \a _li wasn't less than the total number of links in
                        the stream, or the stream was only partially open.*/
 ogg_int64_t op_pcm_total(const OggOpusFile *_of,int _li) OP_ARG_NONNULL(1);
@@ -1641,10 +1645,10 @@ ogg_int64_t op_pcm_tell(const OggOpusFile *_of) OP_ARG_NONNULL(1);
 /*@{*/
 /**\name Functions for seeking in Opus streams
 
-   These functions let you seek in Opus streams, if the underlying source
+   These functions let you seek in Opus streams, if the underlying stream
     support it.
    Seeking is implemented for all built-in stream I/O routines, though some
-    individual sources may not be seekable (pipes, live HTTP streams, or HTTP
+    individual streams may not be seekable (pipes, live HTTP streams, or HTTP
     streams from a server that does not support <code>Range</code> requests).
 
    op_raw_seek() is the fastest: it is guaranteed to perform at most one
index 0f2ae39..9ac17e0 100644 (file)
@@ -153,16 +153,16 @@ struct OggOpusLink{
 };
 
 struct OggOpusFile{
-  /*The callbacks used to access the data source.*/
+  /*The callbacks used to access the stream.*/
   OpusFileCallbacks  callbacks;
   /*A FILE *, memory buffer, etc.*/
-  void              *source;
-  /*Whether or not we can seek with this data source.*/
+  void              *stream;
+  /*Whether or not we can seek with this stream.*/
   int                seekable;
   /*The number of links in this chained Ogg Opus file.*/
   int                nlinks;
   /*The cached information from each link in a chained Ogg Opus file.
-    If source isn't seekable (e.g., it's a pipe), only the current link
+    If stream isn't seekable (e.g., it's a pipe), only the current link
      appears.*/
   OggOpusLink       *links;
   /*The number of serial numbers from a single link.*/
@@ -179,9 +179,9 @@ struct OggOpusFile{
     After a call to op_get_next_page(), this will point to the first byte after
      that page.*/
   opus_int64         offset;
-  /*The total size of this data source, or -1 if it's unseekable.*/
+  /*The total size of this stream, or -1 if it's unseekable.*/
   opus_int64         end;
-  /*Used to locate pages in the data source.*/
+  /*Used to locate pages in the stream.*/
   ogg_sync_state     oy;
   /*One of OP_NOTOPEN, OP_PARTOPEN, OP_OPENED, OP_STREAMSET, OP_INITSET.*/
   int                ready_state;
index d25ef48..972a35f 100644 (file)
@@ -148,7 +148,7 @@ static int op_get_data(OggOpusFile *_of,int _nbytes){
   int            nbytes;
   OP_ASSERT(_nbytes>0);
   buffer=(unsigned char *)ogg_sync_buffer(&_of->oy,_nbytes);
-  nbytes=(int)(*_of->callbacks.read)(_of->source,buffer,_nbytes);
+  nbytes=(int)(*_of->callbacks.read)(_of->stream,buffer,_nbytes);
   OP_ASSERT(nbytes<=_nbytes);
   if(OP_LIKELY(nbytes>0))ogg_sync_wrote(&_of->oy,nbytes);
   return nbytes;
@@ -158,7 +158,7 @@ static int op_get_data(OggOpusFile *_of,int _nbytes){
 static int op_seek_helper(OggOpusFile *_of,opus_int64 _offset){
   if(_offset==_of->offset)return 0;
   if(_of->callbacks.seek==NULL
-   ||(*_of->callbacks.seek)(_of->source,_offset,SEEK_SET)){
+   ||(*_of->callbacks.seek)(_of->stream,_offset,SEEK_SET)){
     return OP_EREAD;
   }
   _of->offset=_offset;
@@ -166,7 +166,7 @@ static int op_seek_helper(OggOpusFile *_of,opus_int64 _offset){
   return 0;
 }
 
-/*Get the current position indicator of the underlying source.
+/*Get the current position indicator of the underlying stream.
   This should be the same as the value reported by tell().*/
 static opus_int64 op_position(const OggOpusFile *_of){
   /*The current position indicator is _not_ simply offset.
@@ -370,7 +370,7 @@ static int op_get_prev_page_serial(OggOpusFile *_of,OpusSeekRecord *_sr,
       search_start=llret+1;
     }
     /*We started from the beginning of the stream and found nothing.
-      This should be impossible unless the contents of the source changed out
+      This should be impossible unless the contents of the stream changed out
        from under us after we read from it.*/
     if(OP_UNLIKELY(!begin)&&OP_UNLIKELY(_offset<0))return OP_EBADLINK;
     /*Bump up the chunk size.
@@ -456,7 +456,7 @@ static opus_int64 op_get_last_page(OggOpusFile *_of,ogg_int64_t *_gp,
       }
     }
     /*We started from at or before the beginning of the link and found nothing.
-      This should be impossible unless the contents of the source changed out
+      This should be impossible unless the contents of the stream changed out
        from under us after we read from it.*/
     if((OP_UNLIKELY(left_link)||OP_UNLIKELY(!begin))&&OP_UNLIKELY(_offset<0)){
       return OP_EBADLINK;
@@ -1395,8 +1395,8 @@ static int op_open_seekable2_impl(OggOpusFile *_of){
   opus_int64     data_offset;
   int            ret;
   /*We can seek, so set out learning all about this file.*/
-  (*_of->callbacks.seek)(_of->source,0,SEEK_END);
-  _of->offset=_of->end=(*_of->callbacks.tell)(_of->source);
+  (*_of->callbacks.seek)(_of->stream,0,SEEK_END);
+  _of->offset=_of->end=(*_of->callbacks.tell)(_of->stream);
   if(OP_UNLIKELY(_of->end<0))return OP_EREAD;
   data_offset=_of->links[0].data_offset;
   if(OP_UNLIKELY(_of->end<data_offset))return OP_EBADLINK;
@@ -1441,7 +1441,7 @@ static int op_open_seekable2(OggOpusFile *_of){
   prev_page_offset=_of->prev_page_offset;
   start_offset=_of->offset;
   memcpy(op_start,_of->op,sizeof(*op_start)*start_op_count);
-  OP_ASSERT((*_of->callbacks.tell)(_of->source)==op_position(_of));
+  OP_ASSERT((*_of->callbacks.tell)(_of->stream)==op_position(_of));
   ogg_sync_init(&_of->oy);
   ogg_stream_init(&_of->os,-1);
   ret=op_open_seekable2_impl(_of);
@@ -1459,7 +1459,7 @@ static int op_open_seekable2(OggOpusFile *_of){
   _of->cur_discard_count=_of->links[0].head.pre_skip;
   if(OP_UNLIKELY(ret<0))return ret;
   /*And restore the position indicator.*/
-  ret=(*_of->callbacks.seek)(_of->source,op_position(_of),SEEK_SET);
+  ret=(*_of->callbacks.seek)(_of->stream,op_position(_of),SEEK_SET);
   return OP_UNLIKELY(ret<0)?OP_EREAD:0;
 }
 
@@ -1498,11 +1498,11 @@ static void op_clear(OggOpusFile *_of){
   _ogg_free(_of->serialnos);
   ogg_stream_clear(&_of->os);
   ogg_sync_clear(&_of->oy);
-  if(_of->callbacks.close!=NULL)(*_of->callbacks.close)(_of->source);
+  if(_of->callbacks.close!=NULL)(*_of->callbacks.close)(_of->stream);
 }
 
 static int op_open1(OggOpusFile *_of,
- void *_source,const OpusFileCallbacks *_cb,
+ void *_stream,const OpusFileCallbacks *_cb,
  const unsigned char *_initial_data,size_t _initial_bytes){
   ogg_page  og;
   ogg_page *pog;
@@ -1511,7 +1511,7 @@ static int op_open1(OggOpusFile *_of,
   memset(_of,0,sizeof(*_of));
   if(OP_UNLIKELY(_initial_bytes>(size_t)LONG_MAX))return OP_EFAULT;
   _of->end=-1;
-  _of->source=_source;
+  _of->stream=_stream;
   *&_of->callbacks=*_cb;
   /*At a minimum, we need to be able to read data.*/
   if(OP_UNLIKELY(_of->callbacks.read==NULL))return OP_EREAD;
@@ -1532,12 +1532,12 @@ static int op_open1(OggOpusFile *_of,
   }
   /*Can we seek?
     Stevens suggests the seek test is portable.*/
-  seekable=_cb->seek!=NULL&&(*_cb->seek)(_source,0,SEEK_CUR)!=-1;
+  seekable=_cb->seek!=NULL&&(*_cb->seek)(_stream,0,SEEK_CUR)!=-1;
   /*If seek is implemented, tell must also be implemented.*/
   if(seekable){
     opus_int64 pos;
     if(OP_UNLIKELY(_of->callbacks.tell==NULL))return OP_EINVAL;
-    pos=(*_of->callbacks.tell)(_of->source);
+    pos=(*_of->callbacks.tell)(_of->stream);
     /*If the current position is not equal to the initial bytes consumed,
        absolute seeking will not work.*/
     if(OP_UNLIKELY(pos!=(opus_int64)_initial_bytes))return OP_EINVAL;
@@ -1596,14 +1596,14 @@ static int op_open2(OggOpusFile *_of){
   return ret;
 }
 
-OggOpusFile *op_test_callbacks(void *_source,const OpusFileCallbacks *_cb,
+OggOpusFile *op_test_callbacks(void *_stream,const OpusFileCallbacks *_cb,
  const unsigned char *_initial_data,size_t _initial_bytes,int *_error){
   OggOpusFile *of;
   int          ret;
   of=(OggOpusFile *)_ogg_malloc(sizeof(*of));
   ret=OP_EFAULT;
   if(OP_LIKELY(of!=NULL)){
-    ret=op_open1(of,_source,_cb,_initial_data,_initial_bytes);
+    ret=op_open1(of,_stream,_cb,_initial_data,_initial_bytes);
     if(OP_LIKELY(ret>=0)){
       if(_error!=NULL)*_error=0;
       return of;
@@ -1617,10 +1617,10 @@ OggOpusFile *op_test_callbacks(void *_source,const OpusFileCallbacks *_cb,
   return NULL;
 }
 
-OggOpusFile *op_open_callbacks(void *_source,const OpusFileCallbacks *_cb,
+OggOpusFile *op_open_callbacks(void *_stream,const OpusFileCallbacks *_cb,
  const unsigned char *_initial_data,size_t _initial_bytes,int *_error){
   OggOpusFile *of;
-  of=op_test_callbacks(_source,_cb,_initial_data,_initial_bytes,_error);
+  of=op_test_callbacks(_stream,_cb,_initial_data,_initial_bytes,_error);
   if(OP_LIKELY(of!=NULL)){
     int ret;
     ret=op_open2(of);
@@ -1633,15 +1633,15 @@ OggOpusFile *op_open_callbacks(void *_source,const OpusFileCallbacks *_cb,
 
 /*Convenience routine to clean up from failure for the open functions that
    create their own streams.*/
-static OggOpusFile *op_open_close_on_failure(void *_source,
+static OggOpusFile *op_open_close_on_failure(void *_stream,
  const OpusFileCallbacks *_cb,int *_error){
   OggOpusFile *of;
-  if(OP_UNLIKELY(_source==NULL)){
+  if(OP_UNLIKELY(_stream==NULL)){
     if(_error!=NULL)*_error=OP_EFAULT;
     return NULL;
   }
-  of=op_open_callbacks(_source,_cb,NULL,0,_error);
-  if(OP_UNLIKELY(of==NULL))(*_cb->close)(_source);
+  of=op_open_callbacks(_stream,_cb,NULL,0,_error);
+  if(OP_UNLIKELY(of==NULL))(*_cb->close)(_stream);
   return of;
 }
 
@@ -1659,15 +1659,15 @@ OggOpusFile *op_open_memory(const unsigned char *_data,size_t _size,
 
 /*Convenience routine to clean up from failure for the open functions that
    create their own streams.*/
-static OggOpusFile *op_test_close_on_failure(void *_source,
+static OggOpusFile *op_test_close_on_failure(void *_stream,
  const OpusFileCallbacks *_cb,int *_error){
   OggOpusFile *of;
-  if(OP_UNLIKELY(_source==NULL)){
+  if(OP_UNLIKELY(_stream==NULL)){
     if(_error!=NULL)*_error=OP_EFAULT;
     return NULL;
   }
-  of=op_test_callbacks(_source,_cb,NULL,0,_error);
-  if(OP_UNLIKELY(of==NULL))(*_cb->close)(_source);
+  of=op_test_callbacks(_stream,_cb,NULL,0,_error);
+  if(OP_UNLIKELY(of==NULL))(*_cb->close)(_stream);
   return of;
 }