modules/datamatrix/API.txt

// $Id$

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/>
1	// $Id$
2
3	Data Matrix API for Drupal
4	==========================
5	This is a developers' guide to the Data Matrix API for Drupal 6.x.
6
7
8	CONSTANTS
9	---------
10
11	DATAMATRIX_DMTXWRITE
12
13	A file system path to the `dmtxwrite' binary. On Unix systems, this
14	would typically be `/usr/bin/dmtxwrite' or `/usr/local/bin/dmtxwrite'.
15	On Mac OS X with MacPorts the path is `/opt/local/bin/dmtxwrite'.
16
17	The constant's value is configurable by the Drupal administrator via the
18	<admin/settings/datamatrix> settings screen.
19
20	This constant would typically be used for calling datamatrix_exec().
21
22	DATAMATRIX_DMTXREAD
23
24	A file system path to the `dmtxread' binary. On Unix systems, this
25	would typically be `/usr/bin/dmtxread' or `/usr/local/bin/dmtxread'.
26	On Mac OS X with MacPorts the path is `/opt/local/bin/dmtxread'.
27
28	The constant's value is configurable by the Drupal administrator via the
29	<admin/settings/datamatrix> settings screen.
30
31	This constant would typically be used for calling datamatrix_exec().
32
33
34	FUNCTIONS
35	---------
36
37	Generic
38	~~~~~~~
39
40	string datamatrix_version()
41
42	Returns the libdmtx version number by calling `dmtxwrite --version'.
43	If there is a problem executing this command (e.g. because libdmtx
44	isn't installed, or because the binary paths given in the module's
45	configuration settings are incorrect), NULL is returned.
46
47	Encoding
48	~~~~~~~~
49
50	string datamatrix_encode(string $data, array $options = array())
51
52	Encodes the given input data as a Data Matrix barcode.
53
54	The $data argument should contain a string with the data to be
55	encoded, and the function returns a file path to the encoded image
56	file (which, by default, will be in PNG format).
57
58	Returns FALSE if the encoding fails for any reason.
59
60	The $options array is passed through to datamatrix_exec(), but is
61	first amended as follows:
62
63	* If the 'format' option is not explicitly given, defaults to 'p'
64	(PNG). Currently the only other format supported by `dmtxwrite' is
65	'm' (PNM).
66
67	* If the 'output' option is not explicitly given, defaults to
68	`/tmp/libdmtx_XXXX.png', where `/tmp' is Drupal's temporary file's
69	directory and XXXX is a random string. If you change the 'format'
70	option, you had better also explicitly specify this option or
71	you'll end up with an incorrect file extension.
72
73	See the `dmtxwrite' man page for more available options:
74
75	<http://www.libdmtx.org/display.php?text=dmtxwrite.1>
76
77	Decoding
78	~~~~~~~~
79
80	string datamatrix_decode(string $file, array $options = array())
81
82	Decodes an image file containing a Data Matrix barcode.
83
84	The $file argument should contain a relative or absolute file path to
85	an image file of a Data Matrix barcode. Note that the `dmtxread'
86	command uses the file extension to figure out the image format, so you
87	had better make sure to pass one, and for it to be the correct one.
88
89	Returns FALSE if the decoding fails for any reason, including that of
90	a missing or invalid file extension. In addition, a warning will be
91	triggered if the input file doesn't exist or isn't readable by the web
92	server process.
93
94	The $options array is passed through to datamatrix_exec().
95
96	See the `dmtxread' man page for a list of available options:
97
98	<http://www.libdmtx.org/display.php?text=dmtxread.1>
99
100	Internal
101	~~~~~~~~
102
103	mixed datamatrix_exec(string $command, string $mode = NULL,
104	array $options = array(),
105	[$arg1, $arg2, ..., $argN])
106
107	Executes a `dmtxread' or `dmtxwrite' command using exec()/popen().
108
109	The path to the specific libdmtx binary is given in $command. This
110	would typically be one of the two constants DATAMATRIX_DMTXWRITE and
111	DATAMATRIX_DMTXREAD.
112
113	When called with $mode = NULL, delegates to exec() and returns an
114	array containing every line of output from the command.
115
116	When called with $mode = 'r' \|\| 'w', delegates to popen() and returns
117	a unidirectional input/output stream resource (the caller is
118	responsible for calling pclose() to close the stream).
119
120	Indiscriminately returns FALSE on failure, whether the problem was in
121	not being able to execute the command in the first place (e.g. the
122	binary doesn't exist) or in getting a failed exit status from the
123	invoked program. No warnings are triggered.
124
125	The $options array should contain key/value pairs that will be
126	transformed to command-line options for the command to be executed.
127
128	For example, this input array:
129
130	$options = array('encoding' => 't', 'mosaic' => TRUE)
131
132	...will get transformed into these command-line options:
133
134	--encoding=t --mosaic
135
136	Note that all the values given in $options will get passed through
137	escapeshellarg(). The keys will get passed through as they are.
138
139	Any further arguments to this function will be filtered through
140	escapeshellarg() and get appended to the command line as they are,
141	each one prepended with a space. This is how you would pass in e.g.
142	file paths.
143
144
145	MISCELLANEOUS
146	-------------
147	To add the Data Matrix API as a dependency in your Drupal module, simply
148	include the following line to your module's .info file:
149
150	dependencies[] = datamatrix
151
152
153	CREDITS
154	-------
155	Developed and maintained by Arto Bendiken <http://ar.to/>