GraphicsMagick

- Home
- Project
- Download
- Install
- Source
- News
- Utilities
- Programming
- Reference

# blob

## Read or write formatted images in memory (BLOBs)

Contents

- AttachBlob
- BlobIsSeekable
- BlobReserveSize
- BlobToFile
- BlobToImage
- CloneBlobInfo
- DestroyBlob
- DestroyBlobInfo
- DetachBlob
- FileToBlob
- GetBlobFileHandle
- GetBlobInfo
- GetBlobStatus
- GetBlobFirstErrno
- GetBlobStreamData
- GetBlobTemporary
- GetConfigureBlob
- ImageToBlob
- ImageToFile
- PingBlob
- ReferenceBlob
- SetBlobClosable
- SetBlobTemporary

# AttachBlob

## Synopsis

    void AttachBlob( BlobInfo *blob_info, const void *blob, const size_t length );

## Description

AttachBlob() attaches a blob to the BlobInfo structure.

The format of the AttachBlob method is:

    void AttachBlob( BlobInfo *blob_info, const void *blob, const size_t length );

A description of each parameter follows:

blob_info:
  Specifies a pointer to a BlobInfo structure.
blob:
  The address of a character stream in one of the image formats understood by GraphicsMagick.
length:
  This size_t integer reflects the length in bytes of the blob.

# BlobIsSeekable

## Synopsis

    MagickBool BlobIsSeekable( const Image *image );

## Description

BlobIsSeekable() returns MagickTrue if the blob supports seeks (SeekBlob() is functional).

The format of the BlobIsSeekable method is:

    MagickBool BlobIsSeekable( const Image *image );

A description of each parameter follows:

image:
  Image to query

# BlobReserveSize

## Synopsis

    MagickPassFail BlobReserveSize( Image *image, magick_off_t size );

## Description

BlobReserveSize() sets the output size of the blob or file. This is used as a means to minimize memory or filesystem fragmentation if the final output size is known in advance. While it is possible that file fragmentation is reduced, it is also possible that file write performance is reduced by changing a write operation to a read, modify, write operation.

The format of the BlobReserveSize method is:

    MagickPassFail BlobReserveSize( Image *image, magick_off_t size );

A description of each parameter follows:

image:
  Image to update
size:
  New output size.

# BlobToFile

## Synopsis

    MagickPassFail BlobToFile( const char *filename, const void *blob, const size_t length,
                               ExceptionInfo *exception );

## Description

BlobToFile() writes a blob to a file. It returns MagickFail if an error occurs otherwise MagickPass.

The format of the BlobToFile method is:

    MagickPassFail BlobToFile( const char *filename, const void *blob, const size_t length,
                               ExceptionInfo *exception );

status:
  BlobToFile returns MagickPass on success; otherwise, it returns MagickFail if an error occurs.
filename:
  Write the blob to this file.
blob:
  The address of a blob.
length:
  This length in bytes of the blob.
exception:
  Return any errors or warnings in this structure.

# BlobToImage

## Synopsis

    Image *BlobToImage( const ImageInfo *image_info, const void *blob,
                        const size_t length, ExceptionInfo *exception );

## Description

BlobToImage() implements direct to memory image formats. It returns the blob as an image.

The format of the BlobToImage method is:

    Image *BlobToImage( const ImageInfo *image_info, const void *blob,
                        const size_t length, ExceptionInfo *exception );

image_info:
  The image info.
blob:
  The address of a character stream in one of the image formats understood by GraphicsMagick.
length:
  This size_t integer reflects the length in bytes of the blob.
exception:
  Return any errors or warnings in this structure.

# CloneBlobInfo

## Synopsis

    BlobInfo *CloneBlobInfo( const BlobInfo *blob_info );

## Description

CloneBlobInfo() makes a duplicate of the given blob info structure, or if blob info is NULL, a new one.

The format of the CloneBlobInfo method is:

    BlobInfo *CloneBlobInfo( const BlobInfo *blob_info );

A description of each parameter follows:

clone_info:
  Method CloneBlobInfo returns a duplicate of the given blob info, or if blob info is NULL a new one.
quantize_info:
  a structure of type info.

# DestroyBlob

## Synopsis

    void DestroyBlob( Image *image );

## Description

DestroyBlob() deallocates memory associated with a blob. The blob is a reference counted object so the object is only destroyed once its reference count decreases to zero.

The format of the DestroyBlob method is:

    void DestroyBlob( Image *image );

A description of each parameter follows:

image:
  The image.

# DestroyBlobInfo

## Synopsis

    void DestroyBlobInfo( BlobInfo *blob );

## Description

DestroyBlobInfo() deallocates memory associated with an BlobInfo structure. The blob is a reference counted object so the object is only destroyed once its reference count decreases to zero. Use of DestroyBlob is preferred over this function since it assures that the blob is closed prior to destruction.

This function is no longer used within GraphicsMagick.

The format of the DestroyBlobInfo method is:

    void DestroyBlobInfo( BlobInfo *blob );

A description of each parameter follows:

blob:
  Specifies a pointer to a BlobInfo structure.

# DetachBlob

## Synopsis

    void DetachBlob( BlobInfo *blob_info );

## Description

DetachBlob() detaches a blob from the BlobInfo structure.

The format of the DetachBlob method is:

    void DetachBlob( BlobInfo *blob_info );

A description of each parameter follows:

blob_info:
  Specifies a pointer to a BlobInfo structure.

# FileToBlob

## Synopsis

    void *FileToBlob( const char *filename, size_t *length, ExceptionInfo *exception );

## Description

FileToBlob() returns the contents of a file in a buffer allocated via MagickMalloc() (which is equivalent to the system malloc() by default). The character '0' is appended to the buffer in case the buffer will be accessed as a string. The length of the buffer (not including the extra terminating '0' character) is returned via the 'length' parameter. If an error occurs, a NULL pointer is returned. The returned buffer must be freed by the user in a matter compatible with MagickMalloc() (e.g. via MagickFree()).

The format of the FileToBlob method is:

    void *FileToBlob( const char *filename, size_t *length, ExceptionInfo *exception );

blob:
  FileToBlob() returns the contents of a file as a blob. If an error occurs NULL is returned.
filename:
  The filename.
length:
  This pointer to a size_t integer sets the initial length of the blob. On return, it reflects the actual length of the blob.
exception:
  Return any errors or warnings in this structure.

# GetBlobFileHandle

## Synopsis

    FILE *GetBlobFileHandle( const Image *image );

## Description

GetBlobFileHandle() returns the stdio file handle associated with the image blob. If there is no associated file handle, then a null pointer is returned.

The format of the GetBlobFileHandle method is:

    FILE *GetBlobFileHandle( const Image *image );

A description of each parameter follows:

image:
  Image to query

# GetBlobInfo

## Synopsis

    void GetBlobInfo( BlobInfo *blob_info );

## Description

GetBlobInfo() initializes the BlobInfo structure.

The format of the GetBlobInfo method is:

    void GetBlobInfo( BlobInfo *blob_info );

A description of each parameter follows:

blob_info:
  Specifies a pointer to a BlobInfo structure.

# GetBlobStatus

## Synopsis

    int GetBlobStatus( const Image *image );

## Description

GetBlobStatus() returns the blob error status. For GraphicsMagick 1.3.26 and earlier, this was only set by CloseBlob() but now it is set immediately upon error.

The format of the GetBlobStatus method is:

    int GetBlobStatus( const Image *image );

A description of each parameter follows:

image:
  The image.

# GetBlobFirstErrno

## Synopsis

    int GetBlobFirstErrno( const Image *image );

## Description

GetBlobFirstErrno() returns the errno present (if any) when the blob first encountered as error, as indicated by GetBlobStatus(). The the purpose of this function is to help improve the quality of error reporting.

The format of the GetBlobFirstErrno method is:

    int GetBlobFirstErrno( const Image *image );

A description of each parameter follows:

image:
  The image.

# GetBlobStreamData

## Synopsis

    unsigned char *GetBlobStreamData( const Image *image );

## Description

GetBlobStreamData() returns the stream data for the image. The data is only available if the data is stored on the heap, or is memory mapped. Otherwise a NULL value is returned.

The format of the GetBlobStreamData method is:

    unsigned char *GetBlobStreamData( const Image *image );

A description of each parameter follows:

image:
  The image.

# GetBlobTemporary

## Synopsis

    MagickBool GetBlobTemporary( const Image *image );

## Description

GetBlobTemporary() returns MagickTrue if the file associated with the blob is a temporary file and should be removed when the associated image is destroyed.

The format of the GetBlobTemporary method is:

    MagickBool GetBlobTemporary( const Image *image );

A description of each parameter follows:

image:
  Image to query

# GetConfigureBlob

## Synopsis

    void *GetConfigureBlob( const char *filename, ExceptionInfo *exception );

## Description

GetConfigureBlob() returns the specified configure file as a blob.

The format of the GetConfigureBlob method is:

    void *GetConfigureBlob( const char *filename, ExceptionInfo *exception );

A description of each parameter follows:

filename:
  The configure file name.
path:
  return the full path information of the configure file.
length:
  This pointer to a size_t integer sets the initial length of the blob. On return, it reflects the actual length of the blob.
exception:
  Return any errors or warnings in this structure.

# ImageToBlob

## Synopsis

    void *ImageToBlob( const ImageInfo *image_info, Image *image, size_t *length,
                       ExceptionInfo *exception );

## Description

ImageToBlob() implements direct to memory image formats. It returns the image as a formatted blob and its length. The magick member of the Image structure determines the format of the returned blob (GIF, JPEG, PNG, etc.). This function is the equivalent of WriteImage(), but writes the formatted "file" to a memory buffer rather than to an actual file.

The format of the ImageToBlob method is:

    void *ImageToBlob( const ImageInfo *image_info, Image *image, size_t *length,
                       ExceptionInfo *exception );

image_info:
  The image info.
image:
  The image.
length:
  This pointer to a size_t integer sets the initial length of the blob. On return, it reflects the actual length of the blob.
exception:
  Return any errors or warnings in this structure.

# ImageToFile

## Synopsis

    MagickPassFail ImageToFile( Image *image, const char *filename,
                                ExceptionInfo *exception );

## Description

ImageToFile() copies the input image from an open blob stream to a file. It returns False if an error occurs otherwise True. This function is used to handle coders which are unable to stream the data in using Blob I/O. Instead of streaming the data in, the data is streammed to a temporary file, and the coder accesses the temorary file directly.

The format of the ImageToFile method is:

    MagickPassFail ImageToFile( Image *image, const char *filename,
                                ExceptionInfo *exception );

status:
  ImageToFile returns MagickPass on success; otherwise, it returns MagickFail if an error occurs.
image:
  The image.
filename:
  Write the image to this file.
exception:
  Return any errors or warnings in this structure.

# PingBlob

## Synopsis

    Image *PingBlob( const ImageInfo *image_info, const void *blob, const size_t length,
                     ExceptionInfo *exception );

## Description

PingBlob() returns all the attributes of an image or image sequence except for the pixels. It is much faster and consumes far less memory than BlobToImage(). On failure, a NULL image is returned and exception describes the reason for the failure.

The format of the PingBlob method is:

    Image *PingBlob( const ImageInfo *image_info, const void *blob, const size_t length,
                     ExceptionInfo *exception );

image_info:
  The image info.
blob:
  The address of a character stream in one of the image formats understood by GraphicsMagick.
length:
  This size_t integer reflects the length in bytes of the blob.
exception:
  Return any errors or warnings in this structure.

# ReferenceBlob

## Synopsis

    BlobInfo ReferenceBlob( BlobInfo *blob_info );

## Description

ReferenceBlob() increments the reference count associated with the pixel blob, returning a pointer to the blob.

The format of the ReferenceBlob method is:

    BlobInfo ReferenceBlob( BlobInfo *blob_info );

A description of each parameter follows:

blob_info:
  The blob_info.

# SetBlobClosable

## Synopsis

    void SetBlobClosable( Image *image, MagickBool closeable );

## Description

SetBlobClosable() enables closing the blob if MagickTrue is passed, and exempts the blob from being closed if False is passed. Blobs are closable by default (default MagickTrue).

The format of the SetBlobClosable method is:

    void SetBlobClosable( Image *image, MagickBool closeable );

A description of each parameter follows:

image:
  Image to update
closeable:
  Set to FALSE in order to disable closing the blob.

# SetBlobTemporary

## Synopsis

    void SetBlobTemporary( Image *image, MagickBool isTemporary );

## Description

SetBlobTemporary() sets a boolean flag (default False) to specify if the file associated with the blob is a temporary file and should be removed when the associated image is destroyed.

The format of the SetBlobTemporary method is:

    void SetBlobTemporary( Image *image, MagickBool isTemporary );

A description of each parameter follows:

image:
  Image to update
isTemporary:
  Set to True to indicate that the file associated with the blob is temporary.