Click or drag to resize

ConnectionBuilder Class

Builds a Connection from a description string. The description string is used to specify a connection to a specific device over TCP or Bluetooth®.
Inheritance Hierarchy
SystemObject
  Zebra.Sdk.CommConnectionBuilder

Namespace: Zebra.Sdk.Comm
Assemblies:  ZebraPrinterSdk (in ZebraPrinterSdk.dll) Version: 3.0.3271
  SdkApi.Desktop (in SdkApi.Desktop.dll) Version: 3.0.3271
Syntax
public class ConnectionBuilder

The ConnectionBuilder type exposes the following members.

Methods
 NameDescription
Public methodStatic memberAddConnectionType Add a connection type to the ConnectionBuilder.
Public methodStatic memberCode exampleBuild Creates a Connection type based on the contents of descriptionString.
Public methodEquals
(Inherited from Object)
Public methodGetHashCode
(Inherited from Object)
Public methodGetType
(Inherited from Object)
Public methodToString
(Inherited from Object)
Top
Remarks

The description string may be of the explicit forms:

"TCP:192.168.1.4:6101" -- creates a TCP connection to the device with IP address 192.168.1.4 on port 6101.
"TCP:192.168.1.4" -- creates a TCP connection to the device with IP address 192.168.1.4 on default port 9100.
"TCP:dnsName:6101" -- creates a TCP connection to the device with 'dnsName' on port 6101.
"TCP:dnsName" -- creates a TCP connection to the device with 'dnsName' on default port 9100.
"TCP_MULTI:192.168.1.4" -- creates a Multichannel TCP connection to the device with '192.168.1.4' using the default ports for both the printing channel(9100) and the status channel(9200).
"TCP_MULTI:192.168.1.4:1234" -- creates a Multichannel TCP connection to the device with '192.168.1.4' using the given port for the printing channel(1234) and the default port for the status channel(9200).
"TCP_MULTI:192.168.1.4:1234:5678" -- creates a Multichannel TCP connection to the device with '192.168.1.4' using the given ports for the printing channel(1234) and the status channel(5678).
"TCP_MULTI:dnsName:1234:5678" -- creates a Multichannel TCP connection to the device with 'dnsName' using the given ports for the printing channel(1234) and the status channel(5678).
"TCP_STATUS:192.168.1.4:1234" -- creates a TCP status only connection to the device with IP address 192.168.1.4 on port 1234.
"TCP_STATUS:192.168.1.4" -- creates a TCP status only connection to the device with IP address 192.168.1.4 on the default status port 9200.
"BT:11:22:33:44:55:66" -- creates a Bluetooth® connection to the device using '11:22:33:44:55:66' as the MAC address.
"BT_MULTI:11:22:33:44:55:66" -- creates a multichannel Bluetooth® connection to the device using '11:22:33:44:55:66' as the MAC address. (Link-OS 2.5 or higher for the status channel)
"BT_STATUS:11:22:33:44:55:66" -- creates a status only Bluetooth® connection to the device using '11:22:33:44:55:66' as the MAC address. (Link-OS 2.5 or higher)
"USB:deviceName" – creates a USB connection (through the ZebraDesigner driver) to the device with printer name 'deviceName'
"USB_DIRECT:deviceName" – creates a USB connection to the device with 'device.unique_id' or 'device.product_name' equal to 'deviceName'*

Generic text may also be used to attempt to specify a device. For example a description string of "genericText" will attempt to connect to a device using the following priority:
  • TCP_MULTI
  • TCP
  • TCP_STATUS
  • BT
If you supply the string '1FE533AA7B90'. This could be interpreted to be either a DNS name or a Bluetooth® MAC address. ConnectionBuilder will attempt to connect to this string given the above priority order. If you supply a more specific string, such as '192.168.2.3', ConnectionBuilder will more efficiently interpret this string as being an IP address and, therefore, only attempt the TCP connections.
The Bluetooth® Connection Building process will first attempt an insecure connection (no pairing required). This requires the printer's 'bluetooth.minimum_security_mode' must be set to 1. If an insecure connection could not be esablished, it will attempt to pair and connect securely. This will trigger the Android pairing request prompt.
Note: Colon (':') characters are not supported in dnsName, friendlyName, uniqueId, deviceName, or genericText fields.

The following is an example of building a connection from a string.
Example
Desktop
C#
using System;
using System.Text;
using Zebra.Sdk.Comm;
using Zebra.Sdk.Printer;
using Zebra.Sdk.Printer.Discovery;

public class ConnectionBuilderExample {

    public static void Main(string[] args) {
        UsbDriverlessTest();

        new ConnectionBuilderExample().NonBlockingStatusReportingOverMultichannel("1.2.3.4");
        new ConnectionBuilderExample().SendZplOverTcp("1.2.3.4");
        new ConnectionBuilderExample().SendZplOverUsb("ZDesigner GK420t");

        // Windows 10 only
        new ConnectionBuilderExample().SendZplOverBluetooth("11:22:33:44:55:66");
    }

    private static void UsbDriverlessTest() {
        Console.WriteLine("Discovered USB printer list:\r\n");
        foreach (DiscoveredUsbPrinter printer in UsbDiscoverer.GetZebraUsbPrinters(new ZebraPrinterFilter())) {
            Console.WriteLine(printer);
        }
        Console.WriteLine("End USB printer list\r\n");

        Connection imz = null;
        try {
            imz = ConnectionBuilder.Build("\\\\?\\usb#vid_0a5f&pid_00f2#imz220#...");
            imz.Open();

            byte[] hi_return = imz.SendAndWaitForResponse(Encoding.UTF8.GetBytes("~HI"), 5000, 10000, "V");
            Console.WriteLine(Encoding.UTF8.GetString(hi_return));
        } finally {
            if (imz != null) {
                imz.Close();
            }
        }
    }

    private void NonBlockingStatusReportingOverMultichannel(string theIpAddress) {
        Connection thePrinterConn = null;
        try {
            // Instantiate Multichannel connection for simultaneous printing and status reporting at given address
            thePrinterConn = ConnectionBuilder.Build($"TCP_MULTI:{theIpAddress}:9100:9200");

            // Opens the connection - physical connection is established here.
            thePrinterConn.Open();

            // Creates a Link-OS printing with the given connection
            ZebraPrinterLinkOs linkOsPrinter = ZebraPrinterFactory.GetLinkOsPrinter(thePrinterConn);

            // This is sent over the printing channel (9100 by default) and will block the printing channel until the
            // label format is completely sent.
            string labelFormatStartCommand = "^XA";
            linkOsPrinter.SendCommand(labelFormatStartCommand);

            string labelBody = "^FO20,20^A0N,25,25^FDThis is a ZPL test.^FS";
            linkOsPrinter.SendCommand(labelBody);

            // This is sent over the status channel (9200 by default) and will return immediately even though the
            // printing channel is in use.
            // If a TcpConnection were used instead of a MultichannelTcpConnection, this would not be possible.
            PrinterStatus status = linkOsPrinter.GetCurrentStatus();

            Console.WriteLine($"The printer PAUSED state is: {status.isPaused}");

            // Send the end of label command to finish and print the label.
            string labelFormatEndCommand = "^XZ";
            linkOsPrinter.SendCommand(labelFormatEndCommand);
        } catch (ConnectionException e) {
            // Handle communications error here.
            Console.WriteLine(e.ToString());
        } finally {
            // Close the connection to release resources.
            if (thePrinterConn != null) {
                thePrinterConn.Close();
            }
        }
    }

    private void SendZplOverTcp(string theIpAddress) {
        Connection thePrinterConn = null;
        try {
            // Instantiate connection for ZPL TCP port at given address
            thePrinterConn = ConnectionBuilder.Build($"TCP:{theIpAddress}:9100");

            // Open the connection - physical connection is established here.
            thePrinterConn.Open();

            // This example prints "This is a ZPL test." near the top of the label.
            string zplData = "^XA^FO20,20^A0N,25,25^FDThis is a ZPL test.^FS^XZ";

            // Send the data to printer as a byte array.
            thePrinterConn.Write(Encoding.UTF8.GetBytes(zplData));
        } catch (ConnectionException e) {
            // Handle communications error here.
            Console.WriteLine(e.ToString());
        } finally {
            // Close the connection to release resources.
            if (thePrinterConn != null) {
                thePrinterConn.Close();
            }
        }
    }

    private void SendZplOverUsb(string usbDriverName) {
        Connection thePrinterConn = null;
        try {
            // Instantiate USB connection for ZPL printer through its driver
            thePrinterConn = ConnectionBuilder.Build($"USB:{usbDriverName}");

            // Open the connection - physical connection is established here.
            thePrinterConn.Open();

            // This example prints "This is a ZPL test." near the top of the label.
            string zplData = "^XA^FO20,20^A0N,25,25^FDThis is a ZPL test.^FS^XZ";

            // Send the data to printer as a byte array.
            thePrinterConn.Write(Encoding.UTF8.GetBytes(zplData));
        } catch (ConnectionException e) {
            // Handle communications error here.
            Console.WriteLine(e.ToString());
        } finally {
            // Close the connection to release resources.
            if (thePrinterConn != null) {
                thePrinterConn.Close();
            }
        }
    }

    private void SendZplOverBluetooth(string btMacAddress) {
        Connection thePrinterConn = null;
        try {
            // Instantiate a Bluetooth connection
            thePrinterConn = ConnectionBuilder.Build($"BT:{btMacAddress}");

            // Open the connection - physical connection is established here.
            thePrinterConn.Open();

            // This example prints "This is a ZPL test." near the top of the label.
            string zplData = "^XA^FO20,20^A0N,25,25^FDThis is a ZPL test.^FS^XZ";

            // Send the data to printer as a byte array.
            thePrinterConn.Write(Encoding.UTF8.GetBytes(zplData));
        } catch (ConnectionException e) {
            // Handle communications error here.
            Console.WriteLine(e.ToString());
        } finally {
            // Close the connection to release resources.
            if (thePrinterConn != null) {
                thePrinterConn.Close();
            }
        }
    }
}
See Also