buffer: XML Security Library Reference Manual

## buffer buffer — Binary memory buffer functions. |

## Stability Level

Stable, unless otherwise indicated

## Functions

void | xmlSecBufferSetDefaultAllocMode ()
xmlSecBufferPtr | xmlSecBufferCreate ()
void | xmlSecBufferDestroy ()
int | xmlSecBufferInitialize ()
void | xmlSecBufferFinalize ()
int | xmlSecBufferIsEmpty ()
xmlSecByte * | xmlSecBufferGetData ()
int | xmlSecBufferSetData ()
xmlSecSize | xmlSecBufferGetSize ()
int | xmlSecBufferSetSize ()
xmlSecSize | xmlSecBufferGetMaxSize ()
int | xmlSecBufferSetMaxSize ()
void | xmlSecBufferEmpty ()
void | xmlSecBufferSwap ()
int | xmlSecBufferAppend ()
int | xmlSecBufferPrepend ()
int | xmlSecBufferRemoveHead ()
int | xmlSecBufferRemoveTail ()
int | xmlSecBufferReverse ()
int | xmlSecBufferReadFile ()
int | xmlSecBufferBase64NodeContentRead ()
int | xmlSecBufferBase64NodeContentWrite ()
int | xmlSecBufferHexRead ()
xmlOutputBufferPtr | xmlSecBufferCreateOutputBuffer ()

## Types and Values

enum | xmlSecAllocMode
struct | xmlSecBuffer

## Description

## Functions

### xmlSecBufferSetDefaultAllocMode ()

    void
    xmlSecBufferSetDefaultAllocMode (xmlSecAllocMode defAllocMode,
                                     xmlSecSize defInitialSize);

Sets new global default allocation mode and minimal intial size.

#### Parameters

defAllocMode | the new default buffer allocation mode. |
defInitialSize | the new default buffer minimal intial size. |

### xmlSecBufferCreate ()

    xmlSecBufferPtr
    xmlSecBufferCreate (xmlSecSize size);

Allocates and initializes new memory buffer with given size. Caller is responsible for calling xmlSecBufferDestroy function to free the buffer.

#### Parameters

size | the intial size. |

#### Returns

pointer to newly allocated buffer or NULL if an error occurs.

### xmlSecBufferDestroy ()

    void
    xmlSecBufferDestroy (xmlSecBufferPtr buf);

Destroys buffer object created with xmlSecBufferCreate function.

#### Parameters

buf | the pointer to buffer object. |

### xmlSecBufferInitialize ()

    int
    xmlSecBufferInitialize (xmlSecBufferPtr buf,
                            xmlSecSize size);

Initializes buffer object `buf` . Caller is responsible for calling xmlSecBufferFinalize function to free allocated resources.

#### Parameters

buf | the pointer to buffer object. |
size | the initial buffer size. |

#### Returns

0 on success or a negative value if an error occurs.

### xmlSecBufferFinalize ()

    void
    xmlSecBufferFinalize (xmlSecBufferPtr buf);

Frees allocated resource for a buffer initialized with xmlSecBufferInitialize function.

#### Parameters

buf | the pointer to buffer object. |

### xmlSecBufferIsEmpty ()

    int
    xmlSecBufferIsEmpty (xmlSecBufferPtr buf);

Checks if the `buf` is empty (`buf` is null or `buf` 's data is null or `buf` 's size is zero).

#### Parameters

buf | the pointer to buffer object. |

#### Returns

1 if buffer is empty or 0 otherwise.

### xmlSecBufferGetData ()

    xmlSecByte *
    xmlSecBufferGetData (xmlSecBufferPtr buf);

Gets pointer to buffer's data.

#### Parameters

buf | the pointer to buffer object. |

#### Returns

pointer to buffer's data.

### xmlSecBufferSetData ()

    int
    xmlSecBufferSetData (xmlSecBufferPtr buf,
                         const xmlSecByte *data,
                         xmlSecSize size);

Sets the value of the buffer to `data` .

#### Parameters

buf | the pointer to buffer object. |
data | the data. |
size | the data size. |

#### Returns

0 on success or a negative value if an error occurs.

### xmlSecBufferGetSize ()

    xmlSecSize
    xmlSecBufferGetSize (xmlSecBufferPtr buf);

Gets the current buffer data size.

#### Parameters

buf | the pointer to buffer object. |

#### Returns

the current data size.

### xmlSecBufferSetSize ()

    int
    xmlSecBufferSetSize (xmlSecBufferPtr buf,
                         xmlSecSize size);

Sets new buffer data size. If necessary, buffer grows to have at least `size` bytes.

#### Parameters

buf | the pointer to buffer object. |
size | the new data size. |

#### Returns

0 on success or a negative value if an error occurs.

### xmlSecBufferGetMaxSize ()

    xmlSecSize
    xmlSecBufferGetMaxSize (xmlSecBufferPtr buf);

Gets the maximum (allocated) buffer size.

#### Parameters

buf | the pointer to buffer object. |

#### Returns

the maximum (allocated) buffer size.

### xmlSecBufferSetMaxSize ()

    int
    xmlSecBufferSetMaxSize (xmlSecBufferPtr buf,
                            xmlSecSize size);

Sets new buffer maximum size. If necessary, buffer grows to have at least `size` bytes.

#### Parameters

buf | the pointer to buffer object. |
size | the new maximum size. |

#### Returns

0 on success or a negative value if an error occurs.

### xmlSecBufferEmpty ()

    void
    xmlSecBufferEmpty (xmlSecBufferPtr buf);

Empties the buffer.

#### Parameters

buf | the pointer to buffer object. |

### xmlSecBufferSwap ()

    void
    xmlSecBufferSwap (xmlSecBufferPtr buf1,
                      xmlSecBufferPtr buf2);

Swaps the content of the two buffers.

#### Parameters

buf1 | the pointer to the first buffer object. |
buf2 | the pointer to the second buffer object. |

### xmlSecBufferAppend ()

    int
    xmlSecBufferAppend (xmlSecBufferPtr buf,
                        const xmlSecByte *data,
                        xmlSecSize size);

Appends the `data` after the current data stored in the buffer.

#### Parameters

buf | the pointer to buffer object. |
data | the data. |
size | the data size. |

#### Returns

0 on success or a negative value if an error occurs.

### xmlSecBufferPrepend ()

    int
    xmlSecBufferPrepend (xmlSecBufferPtr buf,
                         const xmlSecByte *data,
                         xmlSecSize size);

Prepends the `data` before the current data stored in the buffer.

#### Parameters

buf | the pointer to buffer object. |
data | the data. |
size | the data size. |

#### Returns

0 on success or a negative value if an error occurs.

### xmlSecBufferRemoveHead ()

    int
    xmlSecBufferRemoveHead (xmlSecBufferPtr buf,
                            xmlSecSize size);

Removes `size` bytes from the beginning of the current buffer.

#### Parameters

buf | the pointer to buffer object. |
size | the number of bytes to be removed. |

#### Returns

0 on success or a negative value if an error occurs.

### xmlSecBufferRemoveTail ()

    int
    xmlSecBufferRemoveTail (xmlSecBufferPtr buf,
                            xmlSecSize size);

Removes `size` bytes from the end of current buffer.

#### Parameters

buf | the pointer to buffer object. |
size | the number of bytes to be removed. |

#### Returns

0 on success or a negative value if an error occurs.

### xmlSecBufferReverse ()

    int
    xmlSecBufferReverse (xmlSecBufferPtr buf);

Reverses order of bytes in the buffer `buf` .

#### Parameters

buf | the pointer to buffer object. |

#### Returns

0 on success or a negative value if an error occurs.

### xmlSecBufferReadFile ()

    int
    xmlSecBufferReadFile (xmlSecBufferPtr buf,
                          const char *filename);

Reads the content of the file `filename` in the buffer.

#### Parameters

buf | the pointer to buffer object. |
filename | the filename. |

#### Returns

0 on success or a negative value if an error occurs.

### xmlSecBufferBase64NodeContentRead ()

    int
    xmlSecBufferBase64NodeContentRead (xmlSecBufferPtr buf,
                                       xmlNodePtr node);

Reads the content of the `node` , base64 decodes it and stores the result in the buffer.

#### Parameters

buf | the pointer to buffer object. |
node | the pointer to node. |

#### Returns

0 on success or a negative value if an error occurs.

### xmlSecBufferBase64NodeContentWrite ()

    int
    xmlSecBufferBase64NodeContentWrite (xmlSecBufferPtr buf,
                                        xmlNodePtr node,
                                        int columns);

Sets the content of the `node` to the base64 encoded buffer data.

#### Parameters

buf | the pointer to buffer object. |
node | the pointer to a node. |
columns | the max line size for base64 encoded data. |

#### Returns

0 on success or a negative value if an error occurs.

### xmlSecBufferHexRead ()

    int
    xmlSecBufferHexRead (xmlSecBufferPtr buf,
                         const xmlChar *hexStr);

Reads content of hex encoded `hexStr` into `buf` .

#### Parameters

buf | the pointer to buffer object. |
hexStr | the hex string. |

#### Returns

0 on success or a negative value if an error occurs.

### xmlSecBufferCreateOutputBuffer ()

    xmlOutputBufferPtr
    xmlSecBufferCreateOutputBuffer (xmlSecBufferPtr buf);

Creates new LibXML output buffer to store data in the `buf` . Caller is responsible for destroying `buf` when processing is done.

#### Parameters

buf | the pointer to buffer. |

#### Returns

pointer to newly allocated output buffer or NULL if an error occurs.

## Types and Values

### enum xmlSecAllocMode

The memory allocation mode (used by `xmlSecBuffer` and `xmlSecList` ).

#### Members

xmlSecAllocModeExact | the memory allocation mode that minimizes total allocated memory size. |
xmlSecAllocModeDouble | the memory allocation mode that tries to minimize the number of malloc calls. |

### struct xmlSecBuffer

    struct xmlSecBuffer {
        xmlSecByte*         data;
        xmlSecSize          size;
        xmlSecSize          maxSize;
        xmlSecAllocMode     allocMode;
    };

Binary data buffer.

#### Members

xmlSecByte *`data`; | the pointer to buffer data. |
xmlSecSize `size`; | the current data size. |
xmlSecSize `maxSize`; | the max data size (allocated buffer size). |
xmlSecAllocMode `allocMode`; | the buffer memory allocation mode. |