GNU General Public License for more details.
*/
-/* $Id$ */
-/****h* silcutil/SILC Buffer Interface
+/****h* silcutil/Buffer Interface
*
* DESCRIPTION
*
- * SilcBuffer is very simple and easy to use, yet you can do to the
- * buffer almost anything you want with its method functions. The buffer
+ * Data buffer interface that provides buffer allocation and manipulation
+ * routines. SilcBuffer is simple and easy to use, yet you can do to the
+ * buffer almost anything you want with its method functions. The buffer
* is constructed of four different data sections that in whole creates
- * the allocated data area.
+ * the allocated data area. See the SilcBuffer context for more information.
+ *
+ * The SilcBuffer context is not thread-safe and if same context must be
+ * used from multiple threads concurrency control must be employed.
*
***/
#ifndef SILCBUFFER_H
#define SILCBUFFER_H
-/****s* silcutil/SilcBufferAPI/SilcBuffer
+/****s* silcutil/SilcBuffer
*
* NAME
*
* SILC Buffer object. Following short description of the fields
* of the buffer.
*
- * EXAMPLE
- *
- * unsiged char *head;
+ * unsiged char *head;
*
* Head of the allocated buffer. This is the start of the allocated
* data area and remains as same throughout the lifetime of the buffer.
* However, the end of the head area or the start of the currently valid
- * data area is variable.
+ * data area is variable. Reallocating the buffer may change the
+ * pointer.
*
* --------------------------------
* | head | data | tail |
*
* Current head section in the buffer is sb->data - sb->head.
*
- * unsigned char *data;
+ * unsigned char *data;
*
* Currently valid data area. This is the start of the currently valid
* main data area. The data area is variable in all directions.
*
* Current valid data area in the buffer is sb->tail - sb->data.
*
- * unsigned char *tail;
+ * unsigned char *tail;
*
* Tail of the buffer. This is the end of the currently valid data area
* or start of the tail area. The start of the tail area is variable.
*
* Current tail section in the buffer is sb->end - sb->tail.
*
- * unsigned char *end;
+ * unsigned char *end;
*
* End of the allocated buffer. This is the end of the allocated data
* area and remains as same throughout the lifetime of the buffer.
*
* Length of the entire buffer is (ie. truelen) sb->end - sb->head.
*
- * Currently valid data area is considered to be the main data area in
- * the buffer. However, the entire buffer is of course valid data and can
- * be used as such. Usually head section of the buffer includes different
- * kind of headers or similar. Data section includes the main data of
- * the buffer. Tail section can be seen as a reserve space of the data
- * section. Tail section can be pulled towards end, and thus the data
- * section becomes larger.
- *
- * SILC Buffer is not thread-safe. If the same SilcBuffer context must be
- * used in multithreaded environment concurrency control must be employed.
+ * Currently valid data area is considered to be the main data area in
+ * the buffer. However, the entire buffer is of course valid data and can
+ * be used as such. Usually head section of the buffer includes different
+ * kind of headers or similar. Data section includes the main data of
+ * the buffer. Tail section can be seen as a reserve space of the data
+ * section. Tail section can be pulled towards end, and thus the data
+ * section becomes larger.
*
* SOURCE
*/
typedef struct SilcBufferObject {
- unsigned char *head;
- unsigned char *data;
- unsigned char *tail;
- unsigned char *end;
+ unsigned char *head; /* Head of the allocated buffer area */
+ unsigned char *data; /* Start of the data area */
+ unsigned char *tail; /* Start of the tail area */
+ unsigned char *end; /* End of the buffer */
} *SilcBuffer, SilcBufferStruct;
/***/
/* Macros */
-/****f* silcutil/SilcBufferAPI/silc_buffer_data
+/****f* silcutil/silc_buffer_data
*
* NAME
*
#define silc_buffer_data(x) (x)->data
/***/
-/****f* silcutil/SilcBufferAPI/silc_buffer_tail
+/****f* silcutil/silc_buffer_tail
*
* NAME
*
#define silc_buffer_tail(x) (x)->tail
/***/
-/****f* silcutil/SilcBufferAPI/silc_buffer_datalen
+/****f* silcutil/silc_buffer_datalen
*
* NAME
*
/* Inline functions */
-/****d* silcutil/SilcBufferAPI/silc_buffer_truelen
+/****d* silcutil/silc_buffer_truelen
*
* NAME
*
return (SilcUInt32)(x->end - x->head);
}
-/****d* silcutil/SilcBufferAPI/silc_buffer_len
+/****d* silcutil/silc_buffer_len
*
* NAME
*
return (SilcUInt32)(x->tail - x->data);
}
-/****d* silcutil/SilcBufferAPI/silc_buffer_headlen
+/****d* silcutil/silc_buffer_headlen
*
* NAME
*
return (SilcUInt32)(x->data - x->head);
}
-/****d* silcutil/SilcBufferAPI/silc_buffer_taillen
+/****d* silcutil/silc_buffer_taillen
*
* NAME
*
return (SilcUInt32)(x->end - x->tail);
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_alloc
+/****f* silcutil/silc_buffer_alloc
*
* SYNOPSIS
*
return sb;
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_salloc
+/****f* silcutil/silc_buffer_salloc
*
* SYNOPSIS
*
return sb;
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_free
+/****f* silcutil/silc_buffer_free
*
* SYNOPSIS
*
}
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_sfree
+/****f* silcutil/silc_buffer_sfree
*
* SYNOPSIS
*
silc_buffer_free(sb);
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_steal
+/****f* silcutil/silc_buffer_steal
*
* SYNOPSIS
*
return buf;
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_purge
+/****f* silcutil/silc_buffer_purge
*
* SYNOPSIS
*
silc_free(silc_buffer_steal(sb, NULL));
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_spurge
+/****f* silcutil/silc_buffer_spurge
*
* SYNOPSIS
*
silc_buffer_purge(sb);
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_set
+/****f* silcutil/silc_buffer_set
*
* SYNOPSIS
*
sb->tail = sb->end = data + data_len;
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_pull
+/****f* silcutil/silc_buffer_pull
*
* SYNOPSIS
*
return old_data;
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_push
+/****f* silcutil/silc_buffer_push
*
* SYNOPSIS
*
return old_data;
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_pull_tail
+/****f* silcutil/silc_buffer_pull_tail
*
* SYNOPSIS
*
return old_tail;
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_push_tail
+/****f* silcutil/silc_buffer_push_tail
*
* SYNOPSIS
*
return old_tail;
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_put_head
+/****f* silcutil/silc_buffer_put_head
*
* SYNOPSIS
*
return (unsigned char *)memcpy(sb->head, data, len);
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_put
+/****f* silcutil/silc_buffer_put
*
* SYNOPSIS
*
return (unsigned char *)memcpy(sb->data, data, len);
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_put_tail
+/****f* silcutil/silc_buffer_put_tail
*
* SYNOPSIS
*
return (unsigned char *)memcpy(sb->tail, data, len);
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_alloc_size
+/****f* silcutil/silc_buffer_alloc_size
*
* SYNOPSIS
*
return sb;
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_salloc_size
+/****f* silcutil/silc_buffer_salloc_size
*
* SYNOPSIS
*
return sb;
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_reset
+/****f* silcutil/silc_buffer_reset
*
* SYNOPSIS
*
sb->data = sb->tail = sb->head;
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_clear
+/****f* silcutil/silc_buffer_clear
*
* SYNOPSIS
*
silc_buffer_reset(sb);
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_start
+/****f* silcutil/silc_buffer_start
*
* SYNOPSIS
*
sb->data = sb->head;
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_end
+/****f* silcutil/silc_buffer_end
*
* SYNOPSIS
*
sb->tail = sb->end;
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_copy
+/****f* silcutil/silc_buffer_copy
*
* SYNOPSIS
*
return sb_new;
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_scopy
+/****f* silcutil/silc_buffer_scopy
*
* SYNOPSIS
*
return sb_new;
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_clone
+/****f* silcutil/silc_buffer_clone
*
* SYNOPSIS
*
return sb_new;
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_sclone
+/****f* silcutil/silc_buffer_sclone
*
* SYNOPSIS
*
return sb_new;
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_realloc
+/****f* silcutil/silc_buffer_realloc
*
* SYNOPSIS
*
return sb;
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_srealloc
+/****f* silcutil/silc_buffer_srealloc
*
* SYNOPSIS
*
return sb;
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_realloc_size
+/****f* silcutil/silc_buffer_realloc_size
*
* SYNOPSIS
*
return sb;
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_srealloc_size
+/****f* silcutil/silc_buffer_srealloc_size
*
* SYNOPSIS
*
return sb;
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_enlarge
+/****f* silcutil/silc_buffer_enlarge
*
* SYNOPSIS
*
return TRUE;
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_senlarge
+/****f* silcutil/silc_buffer_senlarge
*
* SYNOPSIS
*
return TRUE;
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_append
+/****f* silcutil/silc_buffer_append
*
* SYNOPSIS
*
return TRUE;
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_append
+/****f* silcutil/silc_buffer_sappend
*
* SYNOPSIS
*
return TRUE;
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_strchr
+/****f* silcutil/silc_buffer_strchr
*
* SYNOPSIS
*
return NULL;
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_equal
+/****f* silcutil/silc_buffer_equal
*
* SYNOPSIS
*
return memcmp(sb1->data, sb2->data, silc_buffer_len(sb1)) == 0;
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_memcmp
+/****f* silcutil/silc_buffer_memcmp
*
* SYNOPSIS
*
return memcmp(buffer->data, data, data_len) == 0;
}
-/****f* silcutil/SilcBufferAPI/silc_buffer_printf
+/****f* silcutil/silc_buffer_printf
*
* SYNOPSIS
*