Using the API

All elements of the StarMicronics.CloudPRNT-Utility package are available under the StarMicronics.CloudPRNT namespace. At the time, the package provides classes for serialization to/from CloudPRNT JSON messages, a CloudPRNT Status decoder, and a set of classes for handling and converting documents based on images, plain text, or Star Document Markup language.

Where to use

All CloudPRNT servers will vary depending on the individual requirements of the project, therefore, most details of the server development remain entirely with the developer. In many cases, it is expected that CloudPRNT support will be added as feature extension to existing services.

The provided API classes are expected to be used when handling the CloudPRNT POST and GET requests.

When receiving CloudPRNT Poll by HTTP POST

When receiving a CloudPRNT job data request by HTTP GET

  • Servers can fetch or render a print job using any one of the input data formats supported by the API (PNG, JPEG, BMP, GIF, text, Star Document Markup).
  • Servers should prepare a StarMicronics.CloudPrnt.ConversionOptions object to determine how the print job should be prepared (such as whether to use dithering and scaling when printing images).
  • Servers can use the StarMicronics.CloudPrnt.Document static helper methods Convert() or ConvertFromFile() to convert the source document into the media format requested by the CloudPRNT client device.

Serialization Classes

Under the StarMicronics.CloudPRNT.CpMessage namespace are classes that can be used to serialize/de-serialize CloudPRNT polling JSON messages.

The two primary classes are:

A simple CloudPRNT server method to handle CloudPRNT poll requests might look like this (in C#):

string HandleCloudPRNTPoll(string request)
{
	PollRequest pollRequest = JsonConvert.DeserializeObject<PollRequest>(request);
	Console.WriteLine(
		String.Format("Received CloudPRNT request from {0}, status: {1}",
		pollRequest.printerMAC,
		pollRequest.statusCode
	));

	// Create a response object
	PollResponse pollResponse = new PollResponse();

	// do not print anything at this time
	pollResponse.jobReady = false
	pollResponse.mediaTypes = null;

	return JsonConvert.SerializeObject(pollResponse);
}

This code assumes the Newtonsoft.Json package has been installed to this project as well as the StarMicronics.CloudPRNT-Utility package.

Status Decoding

A StarMicronics.CloudPrnt.PrinterStatus class provides a way to easily decode and inspect the Star ASB format status that is returned by Star CloudPRNT clients. When CloudPRNT clients report the printer device status, is is as a string of hex values, encoded according to the Star ASB specification, for example:

"23 86 00 00 00 00 00 00 00 00 00"

This can be decoded into a much easier to process form using the PrinterStatus class. To use this class, pass it the status string as a constructor parameter, for example:

PrinterStatus status = new PrinterStatus("23 86 00 00 00 00 00 00 00 00 00");
If(status.CoverOpen)
	Console.WriteLine("Printer cover is open");

If your code already has a PollRequest object, then you can also use the PollRequest.DecodedStatus property to retrieve a PrinterStatus object. For example:

PollRequest pollRequest = JsonConvert.DeserializeObject<PollRequest>(request);
If(pollRequest.DecodedStatus.CoverOpen)
	Console.WriteLine("Printer cover is open");

Determining possible output media types for a print job

Handling of print documents is performed via classes that implement the ICpDocument interface. At this time there are three core types of document supported by the API:

  • Documents.ImageDoc - Handles documents created graphically, such as from a PNG, JPEG, BMP, GIF source.
  • Documents.TextDoc) - Handles plain text documents created as UTF8 encoded text.
  • Documents.MarkupDoc - Handles documents created using the Star Document Markup Specification.

Each of these ICpDocument implementations can convert their input document to a variety of output formats, to ensure that they can be handled by any Star printer, regardless of its internal command emulation or which media types it is able to decode internally.

It is possible to construct each of these document types directly, but usually more convenient to use the StarMicronics.CloudPrnt.Document static class, which provides factory methods for creating document objects, and can hide the use of ICpDocument classes entirely.

To obtain a list of supported output media types for a particular given input, the simplest way is to use the Document.GetOutputTypesFromType(string) or Document.GetOutputTypesFromFileName(string) methods.

For example, if a server implementation uses Star Document markup to prepare print jobs, it can determine which data formats the API can convert this to with:

string[] availableOutputMediaTypes = Document.GetOutputTypesFromType("text/vnd.star.markup");

or if the job will be provided from a file, then the available output types can be determined from the file name (requires a recognized file extension):

string[] availableOutputMediaTypes = Document.GetOutputTypesFileName("jobs/order.png");

A more complete example of a CloudPRNT POST request handler could be:

string HandleCloudPRNTPoll(string request)
{
	PollRequest pollRequest = JsonConvert.DeserializeObject<PollRequest>(request);
	Console.WriteLine(
		String.Format("Received CloudPRNT request from {0}, status: {1}",
			pollRequest.printerMAC,
			pollRequest.statusCode
		));

	// Create a response object
	PollResponse pollResponse = new PollResponse();

	if (database.jobAvailable(pollRequest.printerMAC))
	{
		pollResponse.jobReady = true;
		pollResponse.mediaTypes = new List<string>();
		pollResponse.mediaTypes.AddRange(Document.GetOutputTypesFromType("text/vnd.star.markup");
	}
	else
	{
		pollResponse.jobReady = false;
		pollResponse.mediaTypes = null;
	}

	return JsonConvert.SerializeObject(pollResponse);
}

Note, in the above example, the object database is just used as an example of an object that may be used to hold the state and requirements for a particular device.

Converting and providing print job data (GET requests)

When a CloudPRNT device has been informed that a print job is available from printing, and provided with a list of available media types (via the poll response), then it will next request the actual print job data via an HTTP GET.

Before downloading a job for printing, a client device will first select it's preferred media type for the job encoding, and then perform an HTTP GET, with the selected media type passed as part of the query string. Servers can ignore the requested media type, and provide the print job in any format that they like, the client will still print it if supported. However this is strongly discouraged, and there are no data formats guaranteed to be supported by all clients.

It is recommended that servers always generate a GET response of the requested media type, to ensure compatibility with all CloudPRNT clients. Servers may use the StarMicronics.CloudPrnt.Document.Convert() and StarMicronics.CloudPrnt.Document.ConvertFromFile() methods to perform this conversion.

For example, to make a print job in Star Document Markup and convert it into the format requested by the client data:

// Make a simple markup language job
StringBuilder job = new StringBuilder();
job.Append("Hello World!\n");
job.Append("[barcode: type code39; data 12345; height 10mm]\n");
job.Append("[cut]");
byte[] jobData = Encoding.UTF8.GetBytes(job.ToString());

// get the requested output media type from the query string
string outputFormat = context.Request.Query["type"];

// set the response media type, and output the converted job to the response body
context.Response.ContentType = outputFormat;
Document.Convert(jobData, "text/vnd.star.markup", context.Response.Body, outputFormat, null);

This code sample is expected to be inside the servers CloudPRNT GET handler, where context is a valid .NET Core HTTPContext object (therefore context.Response.Body is an output stream that will provide the GET response). The final parameter is for a ConversionsObject class, which can be left null to use the defaults (this is not recommended in production, as it will format all output to 80mm).