
Data Matrix API for Drupal
==========================
This is a developers' guide to the Data Matrix API for Drupal 6.x.


CONSTANTS
---------

  DATAMATRIX_DMTXWRITE

    A file system path to the `dmtxwrite' binary. On Unix systems, this
    would typically be `/usr/bin/dmtxwrite' or `/usr/local/bin/dmtxwrite'. 
    On Mac OS X with MacPorts the path is `/opt/local/bin/dmtxwrite'.

    The constant's value is configurable by the Drupal administrator via the
    <admin/settings/datamatrix> settings screen.

    This constant would typically be used for calling datamatrix_exec().

  DATAMATRIX_DMTXREAD

    A file system path to the `dmtxread' binary. On Unix systems, this
    would typically be `/usr/bin/dmtxread' or `/usr/local/bin/dmtxread'.
    On Mac OS X with MacPorts the path is `/opt/local/bin/dmtxread'.

    The constant's value is configurable by the Drupal administrator via the
    <admin/settings/datamatrix> settings screen.

    This constant would typically be used for calling datamatrix_exec().


FUNCTIONS
---------

  Generic
  ~~~~~~~

    string datamatrix_version()

      Returns the libdmtx version number by calling `dmtxwrite --version'. 
      If there is a problem executing this command (e.g. because libdmtx
      isn't installed, or because the binary paths given in the module's
      configuration settings are incorrect), NULL is returned.

  Encoding
  ~~~~~~~~

    string datamatrix_encode(string $data, array $options = array())

      Encodes the given input data as a Data Matrix barcode.

      The $data argument should contain a string with the data to be
      encoded, and the function returns a file path to the encoded image
      file (which, by default, will be in PNG format).

      Returns FALSE if the encoding fails for any reason.

      The $options array is passed through to datamatrix_exec(), but is
      first amended as follows:

        * If the 'format' option is not explicitly given, defaults to 'p'
          (PNG). Currently the only other format supported by `dmtxwrite' is
          'm' (PNM).

        * If the 'output' option is not explicitly given, defaults to
          `/tmp/libdmtx_XXXX.png', where `/tmp' is Drupal's temporary file's
          directory and XXXX is a random string. If you change the 'format'
          option, you had better also explicitly specify this option or
          you'll end up with an incorrect file extension.

      See the `dmtxwrite' man page for more available options:

        <http://www.libdmtx.org/display.php?text=dmtxwrite.1>

  Decoding
  ~~~~~~~~

    string datamatrix_decode(string $file, array $options = array())

      Decodes an image file containing a Data Matrix barcode.

      The $file argument should contain a relative or absolute file path to
      an image file of a Data Matrix barcode. Note that the `dmtxread'
      command uses the file extension to figure out the image format, so you
      had better make sure to pass one, and for it to be the correct one.

      Returns FALSE if the decoding fails for any reason, including that of
      a missing or invalid file extension. In addition, a warning will be
      triggered if the input file doesn't exist or isn't readable by the web
      server process.

      The $options array is passed through to datamatrix_exec().

      See the `dmtxread' man page for a list of available options:

        <http://www.libdmtx.org/display.php?text=dmtxread.1>

  Internal
  ~~~~~~~~

    mixed datamatrix_exec(string $command, string $mode = NULL,
                          array $options = array(),
                          [$arg1, $arg2, ..., $argN])

      Executes a `dmtxread' or `dmtxwrite' command using exec()/popen().

      The path to the specific libdmtx binary is given in $command. This
      would typically be one of the two constants DATAMATRIX_DMTXWRITE and
      DATAMATRIX_DMTXREAD.

      When called with $mode = NULL, delegates to exec() and returns an
      array containing every line of output from the command.

      When called with $mode = 'r' || 'w', delegates to popen() and returns
      a unidirectional input/output stream resource (the caller is
      responsible for calling pclose() to close the stream).

      Indiscriminately returns FALSE on failure, whether the problem was in
      not being able to execute the command in the first place (e.g. the
      binary doesn't exist) or in getting a failed exit status from the
      invoked program. No warnings are triggered.

      The $options array should contain key/value pairs that will be
      transformed to command-line options for the command to be executed.

      For example, this input array:

        $options = array('encoding' => 't', 'mosaic' => TRUE)

      ...will get transformed into these command-line options:

        --encoding=t --mosaic

      Note that all the values given in $options will get passed through
      escapeshellarg(). The keys will get passed through as they are.

      Any further arguments to this function will be filtered through
      escapeshellarg() and get appended to the command line as they are,
      each one prepended with a space. This is how you would pass in e.g.
      file paths.


MISCELLANEOUS
-------------
To add the Data Matrix API as a dependency in your Drupal module, simply
include the following line to your module's .info file:

  dependencies[] = datamatrix


CREDITS
-------
Developed and maintained by Arto Bendiken <http://ar.to/>
