StarMicronics.CloudPRNT-UtilityはNuGetパッケージとして提供され、Visual Studio NuGet UI、nuget コマンドラインユーティリティ、または dotnet コマンドラインユーティリティを介してインストールできます。

StarMicronics.CloudPRNT Utilityパッケージのすべての要素は、名前空間 「StarMicronics.CloudPRNT」で使用できます。
提供されたAPIクラスは、既存のサービスの機能拡張としてCloudPRNTサポートを追加いただいた際に、主にCloudPRNT のPOST／GETリクエストの処理において利用されることを想定しています。

StarMicronics.CloudPRNT.CpMessage名前空間の下には、CloudPRNTポーリングJSONメッセージのシリアライズ/デシリアライズに利用できるクラスがあります。

主なクラスは下記２つのクラスです。

• StarMicronics.CloudPrnt.CpMessage.PollRequest - プリンターからサーバーに定期的に送信されるリクエストbodyをデシリアライズします。
• StarMicronics.CloudPrnt.CpMessage.PollResponse - シリアライズしてサーバーからプリンターへの適切なレスポンスを生成できます。

StarMicronics.CloudPrnt.PrinterStatusクラスは、Star CloudPRNTクライアントによって返されるStar ASB形式のステータスを簡単にデコードおよび検証する方法を提供します。

CloudPRNTクライアントがプリンターデバイスのステータスを報告するとき、Star ASB仕様に従ってエンコードされた16進値の文字列として報告されます。

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

これは、PrinterStatusクラスを使用して処理しやすいフォームにデコードできます。
このクラスを使用するには次の例のようにコンストラクタ文字列としてステータス文字列を渡します。

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

コードに既にPollRequestオブジェクトがある場合は、PrinterStatusオブジェクトを取得するためのPollRequest.DecodedStatusプロパティが利用できます。

PollRequest pollRequest = PollRequest.FromJson(request);
 if(pollRequest.DecodedStatus.CoverOpen)
	Console.WriteLine("Printer cover is open");

印刷ドキュメントの処理は、ICpDocumentインターフェースを実装するクラスを介して実行されます。
現在、APIでサポートされているドキュメントのコアタイプは3つあります。

• Documents.ImageDoc - PNG、JPEG、BMP、GIFソースなどからグラフィカルに作成されたドキュメントを処理します。
• Documents.TextDoc - UTF-8エンコードテキストとして作成されたプレーンテキストドキュメントを処理します。
• Documents.MarkupDoc - Starドキュメントマークアップを使用して作成されたドキュメントを処理します。

これらのICpDocument実装は、それぞれ入力ドキュメントを様々な出力形式に変換してどのStarプリンターでも確実に処理できるようにします。
これらの各ドキュメントタイプを直接構築することは可能ですが、通常はファクトリメソッドを提供するStarMicronics.CloudPrnt.Document静的クラスを使用する方が便利です。 ドキュメントオブジェクトを作成し、ICpDocumentクラスの使用を完全に隠すことができます。

特定の入力に対してサポートされている出力メディアタイプのリストを取得するための最も簡単な方法は、Document.GetOutputTypesFromType(string)または Document.GetOutputTypesFromFileName(string)メソッドです。

たとえば、サーバー実装が Starドキュメントマークアップを使用して印刷ジョブを準備する場合、API がこれをどのデータ形式に変換できるかを決定できます。

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

また、ジョブがファイルから提供される場合、使用可能な出力タイプはファイル名から判別できます（認識できるファイル拡張子が必要です）。

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

CloudPRNT POSTリクエストハンドラの例は以下の通りです。

string HandleCloudPRNTPoll(string request)
{
	PollRequest pollRequest = PollRequest.FromJson(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 pollResponse.ToJson();
}

上記の例では、databaseオブジェクトは特定のデバイスの状態と要件を保持するために使用できるオブジェクトの一例として使用されていることに注意してください。

サーバーから（ポーリングレスポンスによって）印刷ジョブが利用可能であることを通知され、利用可能なメディアタイプのリストが提供されると、CloudPRNTデバイスは次にHTTP GETによって実際の印刷ジョブデータを要求します。

印刷用のジョブをダウンロードする前に、クライアントデバイスは最初にジョブエンコーディングに優先メディアタイプを選択し、選択したメディアタイプをクエリー文字列の一部として渡してHTTP GETを実行します。
サーバーは、要求されたメディアタイプを無視して任意の形式で印刷ジョブを提供することもできます。クライアントデバイスは、その形式がサポートされている場合に印刷します。ただし、この方法は推奨しません。
また、すべてのクライアントデバイスでサポートされることが保証されているデータ形式はありません。

すべてのCloudPRNTクライアントデバイスとの互換性を確保するために、サーバーは常に要求されたメディアタイプのGETレスポンスを生成することを推奨します。
サーバーはStarMicronics.CloudPrnt.Document.Convert()またはStarMicronics.CloudPrnt.Document.ConvertFromFile()メソッドを使用して、この変換を実行できます。

たとえば、Starドキュメントマークアップで印刷ジョブを作成しクライアントデバイスが要求する形式に変換するには下記のようになります。

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

このサンプルコードは、サーバーのCloudPRNT GETハンドラー内にあることが想定されており、context は有効な .NET Core HTTPContext オブジェクトです（したがって、context.Response.Body はGETレスポンスを提供する出力ストリームです）。
最後のパラメーターはConversionsObjectクラス用で、nullのままにしてデフォルトを使用できます（すべての出力を80mmにフォーマットするため、本番環境では推奨されません）。

Starドキュメントマークアップのテンプレート印刷機能を利用する場合はStarMicronics.CloudPRNT.Document.ConvertWithApplyTemplate() またはStarMicronics.CloudPRNT.Document.ConvertFileWithApplyTemplate()メソッドを利用します。

テンプレート印刷機能の仕様はStarドキュメントマークアップマニュアルをご参照ください。

テンプレート印刷機能を利用して印刷ジョブを作成するサンプルは以下のようになります。

コードサンプル

// Make a markup language job that contains replacing specifiers
StringBuilder template = new StringBuilder();
template.Append("Template Sample\n");
template.Append("[column: left ${item1.name}; right ${item1.price}]");
template.Append("[column: left ${item2.name}; right ${item2.price}]");
template.Append("[cut]");
byte[] templateData = Encoding.UTF8.GetBytes(template.ToString());

// Make a json data
string fieldJson =
    """
    {
        "item1": {
            "name": "coffee",
            "price": 5
        },
        "item2": {
            "name": "cake",
            "price": 10
        }
    }
    """;
byte[] fieldData = Encoding.UTF8.GetBytes(fieldJson);

MemoryStream resultStream = new MemoryStream();

// Apply template and get converted job
Document.ConvertWithApplyTemplate(templateData, fieldData, resultStream, "application/vnd.star.starprnt", null);