• Places
    • Home
    • Graphs
    • Prefixes
  • Admin
    • Users
    • Settings
    • Plugins
    • Statistics
  • CPACK
    • Home
    • List packs
    • Submit pack
  • Repository
    • Load local file
    • Load from HTTP
    • Load from library
    • Remove triples
    • Clear repository
  • Query
    • YASGUI SPARQL Editor
    • Simple Form
    • SWISH Prolog shell
  • Help
    • Documentation
    • Tutorial
    • Roadmap
    • HTTP Services
  • Login

12.4.9 BLOBS: Using atoms to store arbitrary binary data
All Application Manual Name SummaryHelp

  • Documentation
    • Reference manual
      • Foreign Language Interface
        • The Foreign Include File
          • BLOBS: Using atoms to store arbitrary binary data
            • Defining a BLOB type
            • Accessing blobs
              • PL_is_blob()
              • PL_unify_blob()
              • PL_put_blob()
              • PL_new_blob()
              • PL_get_blob()
              • PL_blob_data()
              • PL_free_blob()
    • Packages
railing newline. This prototype is available if the SWI-Stream.h is included beforeSWI-Prolog.h. This function can retrieve the data of the blob using PL_blob_data().

Most blobs reference some external data identified by a pointer and the write() function writes <type>(address). If this function is not provided, write/1 emits the content of the blob for blobs of type PL_BLOB_TEXT or a string of the format <#hex data> for binary blobs.

int save(atom_t a, IOSTREAM *s)
Write the blob to stream s, in an opaque form that is known only to the blob. If a “save'' function is not provided (that is, the field is NULL), the default implementation saves and restores the blob as if it is an array of bytes which may contain null (’
0'
) bytes.

SWI-Stream.h defines a number of PL_qlf_put_*() functions that write data in a machine-independent form that can be read by the corresponding PL_qlf_get_*() functions.

If the “save'' function encounters an error, it should call PL_warning(), raise an exception (see PL_raise_exception()), and return FALSE.223Details are subject to change. Note that failure to save/restore a blob makes it impossible to compile a file that contains such a blob using qcompile/2 as well as creating a saved state from a program that contains such a blob impossible. Here, contains means that the blob appears in a clause or directive.

atom_t load(IOSTREAM *s)
Read the blob from its saved form as written by the “save'' function of the same blob type. If this cannot be done (e.g., a stream read failure or a corrupted external form), the “load'' function should call PL_warning(), then PL_fatal_error(), and return constFALSE.224Details are subject to change; see the “save'' function. If a “load'' function is not provided (that is, the field is NULL, the default implementation assumes that the blob was written by the default “save'' - that is, as an array of bytes

SWI-Stream.h defines a number of PL_qlf_get_*() functions that read data in a machine-independent form, as written by the by the corresponding PL_qlf_put_*() functions.

The atom that the “load'' function returns can be created using PL_new_blob().

int PL_unregister_blob_type(PL_blob_t *type)
Unlink the blob type from the registered type and transform the type of possible living blobs to unregistered, avoiding further reference to the type structure, functions referred by it, as well as the data. This function returns TRUE if no blobs of this type existed and FALSE otherwise. PL_unregister_blob_type() is intended for the uninstall() hook of foreign modules, avoiding further references to the module.
int PL_register_blob_type(PL_blob_t *type)
This function does not need to be called explicitly. It is called if needed when a blob is created by PL_unify_blob(), PL_put_blob(), or PL_new_blob().

12.4.10.2 Accessing blobs

The blob access functions are similar to the atom accessing functions. Blobs being atoms, the atom functions operate on blobs and vice versa. For clarity and possible future compatibility issues, however, it is not advised to rely on this.

int PL_is_blob(term_t t, PL_blob_t **type)
Succeeds if t refers to a blob, in which case type is filled with the type of the blob.
int PL_unify_blob(term_t t, void *blob, si

ClioPatria (version V3.1.1-42-gd6a756b-DIRTY)