How to use the HTTP POST connection type

With iCody 2.2, we introduced another way to transmit scanned barcode data: The HTTP Post protocol. Using this connection type, iCody is able to send the scanned barcode data and all related information including location informations directly to a web server using the HTTP Post protocol. There, the data can be processed and it is even possible to let iCody wait for and prompt a reply coming from this server.

httpen

To use this great new feature, follow these steps:

  • Select the connection type “HTTP”.
  • Enter the address of your web server script which is able to process the sent data.
  • Decide if the data shall be sent “blind” or if iCody should wait for and prompt a reply. To achieve this, enable “Wait for Reply”.

Important: To use this feature, you have to implement your own web service. Development experiences are necessary!

iCody 3.0 sends a JSON string containing at least the following values plus the workflow items.

iCody provides the following variables which will be available in your server script for further usage: (deprecated since iCody 3)

value

The scanned/selected barcode value

type

The type of the barcode (string)

typeID

The type ID of the barcode (numeric, might be zero)

timestamp

The UNIX timestamp of the scan date and time

location

The scan location

udid

The device’s unique ID

After processing the sent data and if iCody is configured to wait for a HTTP reply, you might send some information on which iCody reacts. The data format you use for this follows the common Apple property list format (documentation). Each command you want to be processed by iCody is packed into a dictionary (encapsulated by tags). The replied data may either contain one dictionary or one array () containing one or several command dictionaries.

The allowed key-value combination and their additional parameters are:

type

Presentation type (this is the tag).

alert

Present an alert box

title The title of the alert box

message The message to show

vibrate

Let the device vibrate (if possible)

sound

Play a sound

name

playSucessSound, playFailureSound

repeat # of repeats (0 – default)

print

Print on connected DPP-xxx or PP-60 printers (needs Linea Pro with bluetooth connectivity or PP-60)

commands Printer command array (see below)

This is an example for the returned plist (please note that this format only passes back one command and so, the dictionary is the root object. If you like to return more commands, see the example below)::
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>type</key>
<string>alert</string>
<key>title</key>
<string>Dies ist der Titel</string>
<key>message</key>
<string>Dies ist die Nachricht.</string>
</dict>
</plist>

Und hier ein einfaches Beispiel in PHP, um die plist zu erzeugen und zurück zu liefern:
<?php
// this PHP scripts writes all given data to a mysql database (which has to exist ...)
// connect to database
$link = mysqli_connect( '<db URL>', '<username>', '<password>', '<database>' );
if( !$link )
exit;

// the insertation stuff
$query = ‘INSERT INTO <table> SET value=’.$_REQUEST[“value”].’, typeID=’.$_REQUEST[“typeID”].’, type=’.$_REQUEST[“type”].’, scandate=’.$_REQUEST[“timestamp”].’, location=’.$_REQUEST[“location”];
$result = mysqli_query( $link, $query );

mysqli_close($link);

// the back channel plist
echo ‘<?xml version=”1.0″ encoding=”UTF-8″?>
<!DOCTYPE plist PUBLIC “-//Apple//DTD PLIST 1.0//EN” “http://www.apple.com/DTDs/PropertyList-1.0.dtd”>
<plist version=”1.0″>
<dict>
<key>type</key>
<string>alert</string>
<key>title</key>
<string>Dies ist der Titel</string>
<key>message</key>
<string>Dies ist die Nachricht.</string>
</dict>
</plist>
‘;
?>

If you want to use the print command, please be aware that you need a Linea Pro with bluetooth module and a DPP-xxx printer or a PP-60 device. The available printer commands, each represented by a dictionary () and all together wrapped in an array (), are:

cmd

The <key> for the following printer commands:

PCFD

Perform a paper feed

value n/203″ (0 – auto) – oprional -

PCFLSH

Flush printer cache and empty (process) queue

PCSLGO

Store image (logo) to the persistent device store

value hex string with image data (without $ or # or 0x)

align
default alignment of logo when printed:
0 – left (default)
1 – center
2 – right
3 – justified

PCLSMRGN

Set left margin

value left margin in px (0 – auto)

PCLSHGHT

Set line height

value line height in px (0 – auto)

PCDLM

Print delimiter (an entire line of one character)

value the character to print (1 digit only)

PCLGO

Print stored logo

value
0 – normal
1 – double width
2 – double height
3 – double width + double height

PCIMG

Print image

value hex string with image data (without $ or # or 0x)

align
0 – left (default)
1 – center
2 – right
3 – justified

PCPT

Print text

value The text to print. It might contain the following control sequences:
{==} reverts all settings to their defaults. It includes font size, style, aligning
{=Fx} selects font size. x ranges from 0 to 1 as follows:
0: FONT_9X16 (hieroglyph characters are using the same width as height, i.e. 16×16)
1: FONT_12X24 (hieroglyph characters are using the same width as height, i.e. 24×24)
{=L} left text aligning
{=C} center text aligning
{=R} right text aligning
{=Rx} text rotation as follows:
0: not rotated
1: rotated 90 degrees
2: rotated 180 degrees
{+/-B} sets or unsets bold font style
{+/-I} sets or unsets italic font style
{+/-U} sets or unsets underline font style
{+/-V} sets or unsets inverse font style
{+/-W} sets or unsets text word-wrapping
{+/-DW} sets or unsets double font width
{+/-DH} sets or unsets double font height

PCPBC

Print barcode

value the value to print

type the barcode symbology ID to use:
kBCRScanTypeUPCA, kBCRScanTypeUPCE, kBCRScanTypeEAN13, kBCRScanTypeEAN8, kBCRScanTypeCODE39, kBCRScanTypeCodebar, kBCRScanTypeCODE93, kBCRScanTypeCODE128, kBCRScanTypePDF417, kBCRScanTypeEAN128

This is a more complex example with several commands (please note the as the root object):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<array>
     <dict>
         <key>type</key>
         <string>sound</string>
         <key>name</key>
         <string>playSuccessSound</string>
         <key>repeat</key>
         <string>1</string>
     </dict>
     <dict>
         <key>type</key>
         <string>print</string>
        <key>commands</key>
        <array>
             <dict>
                 <key>cmd</key>
                 <string>PCPT</string>
                 <key>value</key>
                 <string>{=L}Barcode:#barcode#</string>
             </dict>
             <dict>
                 <key>cmd</key>
                 <string>PCPT</string>
                 <key>value</key>
                 <string>{=L}Type:#type#</string>
             </dict>
             <dict>
                 <key>cmd</key>
                 <string>PCDLM</string>
                 <key>value</key>
                 <string>-</string>
             </dict>
             <dict>
                 <key>cmd</key>
                 <string>PCFLSH</string>
             </dict>
        </array>
     </dict>
</array>
</plist>

 

Another sample .php-file (without any validation or database overhead):

<?php
         // the back channel plist
    echo '<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<array>
     <dict>
         <key>type</key>
         <string>sound</string>
         <key>name</key>
         <string>playSuccessSound</string>
         <key>repeat</key>
         <string>1</string>
     </dict>
     <dict>
         <key>type</key>
         <string>print</string>
        <key>commands</key>
        <array>
             <dict>
                 <key>cmd</key>
                 <string>PCPT</string>
                 <key>value</key>
                 <string>{=L}Barcode: '.$_POST["value"].'</string>
             </dict>
             <dict>
                 <key>cmd</key>
                 <string>PCPT</string>
                 <key>value</key>
                 <string>{=L}Type:    '.$_POST["type"].'</string>
             </dict>
             <dict>
                 <key>cmd</key>
                 <string>PCDLM</string>
                 <key>value</key>
                 <string>-</string>
             </dict>
             <dict>
                 <key>cmd</key>
                 <string>PCFLSH</string>
             </dict>
        </array>
     </dict>
</array>
</plist>
';
?>