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:   SdkApi.Desktop (in SdkApi.Desktop.dll) Version: 2.15.2634
  ZebraPrinterSdk (in ZebraPrinterSdk.dll) Version: 2.15.2521
  ZebraPrinterSdk (in ZebraPrinterSdk.dll) Version: 2.15.2521

Syntax

C++

Copy

public class ConnectionBuilder

Public Class ConnectionBuilder

public ref class ConnectionBuilder

The ConnectionBuilder type exposes the following members.

Methods

	Name	Description
	AddConnectionType	Add a connection type to the ConnectionBuilder.
	Build	Creates a Connection type based on the contents of descriptionString.
	Equals	Determines whether the specified object is equal to the current object. (Inherited from Object.)
	GetHashCode	Serves as the default hash function. (Inherited from Object.)
	GetType	Gets the Type of the current instance. (Inherited from Object.)
	ToString	Returns a string that represents the current object. (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.

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.

Examples

Desktop

Copy

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&amp;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();
            }
        }
    }
}

Examples

Android™

Copy

using Android.App;
using Android.OS;
using Android.Views;
using Android.Widget;
using System;
using System.Text;
using System.Threading.Tasks;
using Zebra.Sdk.Comm;
using Zebra.Sdk.Printer;

public class ConnectionBuilderExample : Activity {

    protected override void OnCreate(Bundle savedInstanceState) {
        base.OnCreate(savedInstanceState);

        LinearLayout layout = (LinearLayout)View.Inflate(this, Android.Resource.Layout.ActivityListItem, null);
        layout.Orientation = Orientation.Vertical;

        Button buttonPrint = new Button(this) {
            Text = "Run Connection Builder Example",
            LayoutParameters = new ViewGroup.LayoutParams(new LinearLayout.LayoutParams(ViewGroup.LayoutParams.WrapContent, ViewGroup.LayoutParams.WrapContent))
        };
        layout.AddView(buttonPrint);

        SetContentView(layout);

        buttonPrint.Click += async (sender, e) => {
            string theIpAddress = "1.2.3.4";
            string theBluetoothMACAddress = "11:22:33:44:55:66";

            await Task.Run(() => {
                NonBlockingStatusReportingOverMultichannel(theIpAddress);
            });

            await Task.Run(() => {
                SendZplOverTcp(theIpAddress);
            });

            await Task.Run(() => {
                SendZplOverBluetooth(theBluetoothMACAddress);
            });
        };
    }

    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();

            // This prints out whether the printer is pause or not.
            RunOnUiThread(() => {
                Toast.MakeText(this.ApplicationContext, $"The printer PAUSED state is: {status.isPaused}", ToastLength.Long).Show();
            });

            // 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 TCP connection
            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 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();
            }
        }
    }
}

Examples

iOS

Copy

using CoreGraphics;
using System;
using System.Text;
using System.Threading.Tasks;
using UIKit;
using Zebra.Sdk.Comm;
using Zebra.Sdk.Printer;

public class ConnectionBuilderExample : UIViewController {

    public ConnectionBuilderExample(IntPtr handle) : base(handle) {
        UIButton testButton = new UIButton(UIButtonType.System) {
            Frame = new CGRect(25, 25, 300, 150)
        };

        testButton.SetTitle("Run Connection Builder Example", UIControlState.Normal);

        testButton.TouchUpInside += async (sender, e) => {
            string theIpAddress = "1.2.3.4";
            string theBluetoothMACAddress = "11:22:33:44:55:66";

            await Task.Run(() => {
                NonBlockingStatusReportingOverMultichannel(theIpAddress);
                SendZplOverTcp(theIpAddress);
                SendZplOverBluetooth(theBluetoothMACAddress);
            });
        };

        View.AddSubview(testButton);
    }

    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();

            // This prints out whether the printer is paused or not.
            ShowAlertMessage("Printer Status", $"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 TCP connection
            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 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 (Exception e) {
            // Handle communications error here.
            Console.WriteLine(e.ToString());
        } finally {
            // Close the connection to release resources.
            if (thePrinterConn != null) {
                thePrinterConn.Close();
            }
        }
    }

    private void ShowAlertMessage(string title, string message) {
        InvokeOnMainThread(() => {
            UIAlertController alertController = UIAlertController.Create(title, message, UIAlertControllerStyle.Alert);
            alertController.AddAction(UIAlertAction.Create("OK", UIAlertActionStyle.Default, null));
            PresentViewController(alertController, true, null);
        });
    }
}

Reference

Zebra.Sdk.Comm Namespace