Revive Point of Service docs from the dead

docfx.json

@@ -303,6 +303,7 @@
                 "docs/core/whats-new/**/**.md": "adegeo",
                 "docs/csharp/**/*.*": "billwagner",
                 "docs/framework/**/**.md": "gewarren",
+                "docs/framework/additional-apis/pos-for-net/**/**.md": "TerryWarwick",
                 "docs/framework/app-domains/**/**.md": "gewarren",
                 "docs/framework/configure-apps/file-schema/network/**/**.md": "karelz",
                 "docs/framework/configure-apps/file-schema/wcf/**/**.md": "HongGit",

docs/breadcrumb/toc.yml

@@ -102,6 +102,10 @@ items:
       - name: Additional APIs
         tocHref: /dotnet/framework/additional-apis/
         topicHref: /dotnet/framework/additional-apis/index
+        items:
+        - name: Point of Service for .NET
+          tocHref: /dotnet/framework/additional-apis/pos-for-net/
+          topicHref: /dotnet/framework/additional-apis/pos-for-net/index
       - name: Application domains and assemblies
         tocHref: /dotnet/framework/app-domains/
         topicHref: /dotnet/framework/app-domains/index

docs/framework/additional-apis/index.md

@@ -32,6 +32,7 @@ Some libraries target specific platforms. For example, the <xref:System.Text.Cod
 | Project | Description |
 | ------- | ----------- |
 | <xref:System.Text.CodePagesEncodingProvider> | Extends the <xref:System.Text.EncodingProvider> class to make code page encodings available to apps that target the Universal Windows Platform. |
+| [Point of Service for .NET](pos-for-net/index.md) | Provides a set of classes that enable you to develop applications that interact with POS devices. |
 
 ## Private APIs
 

docs/framework/additional-apis/pos-for-net/adding-plug-and-play-support.md

@@ -0,0 +1,72 @@
+---
+title: Adding Plug and Play Support
+description: Adding Plug and Play Support (POS for .NET v1.14 SDK Documentation)
+ms.date: 03/03/2014
+ms.topic: how-to
+ms.custom: pos-restored-from-archive
+---
+
+# Adding Plug and Play Support (POS for .NET v1.14 SDK Documentation)
+
+Microsoft Point of Service for .NET (POS for .NET) includes support for Plug and Play devices. By adding Plug and Play support to your Service Objects, applications can become more simple, reliable, and efficient. Service Objects should support it whenever possible.
+
+Implementing Plug and Play support at the Service Object level is very simple. Once you know the hardware ID of your device, simply add a single attribute to your class, <xref:Microsoft.PointOfService.HardwareIdAttribute>. The **HardwareId** attribute is used by <xref:Microsoft.PointOfService.PosExplorer> to intelligently filter out Service Objects from the list of available devices depending on the state of the device. If the Service Object has a **HardwareId** attribute that refers to an installed Plug and Play device, but that device is not connected, the Service Object will be excluded from the **PosExplorer** device list. This list is returned when applications call <xref:Microsoft.PointOfService.PosExplorer.GetDevices>.
+
+Service Objects may also have more than one **HardwareId** attribute, in which case **PosExplorer** associates a union of all specified devices with the Service Object. It is possible to override the **HardwareId** attributes or add to the list of associated hardware on the Service Object without rebuilding the Service Object assembly. For information about overriding or adding the **HardwareId** attribute, see [Plug and Play XML Configuration](plug-and-play-xml-configuration.md).
+
+Only the application is responsible for catching <xref:Microsoft.PointOfService.PosExplorer.DeviceAddedEvent> and <xref:Microsoft.PointOfService.PosExplorer.DeviceRemovedEvent> events and updating its status as appropriate based on the updated device list returned from **PosExplorer**. The Service Object does not need to detect these events.
+
+## To add a HardwareId attribute to your Service Object class
+
+1. Determine the range of hardware IDs for the device or devices that your Service Object supports.
+
+2. Add a **HardwareId** attribute before your class definition using the lowest hardware ID used by your device and the highest. Multiple **HardwareId** attributes may be used to identify multiple ranges of hardware IDs.
+
+## Example
+
+The following sample adds a **HardwareId** attribute to the basic template shown in the previous section.
+
+```csharp
+using System;
+
+using Microsoft.PointOfService;
+using Microsoft.PointOfService.BaseServiceObjects;
+
+namespace SOTemplate
+{
+
+    [HardwareId("HID\\Vid_05e0&amp;Pid_038a",
+                "HID\\Vid_05e0&amp;Pid_038a")]
+
+    [ServiceObject(
+                DeviceType.Msr,
+                "ServiceObjectTemplate",
+                "Bare bones Service Object class",
+                1,
+                9)]
+    public class MyServiceObject : MsrBase
+    {
+        public MyServiceObject()
+        {
+        }
+    }
+}
+
+```
+
+## See Also
+
+#### Tasks
+
+- [Creating a Basic Service Object Code Template](creating-a-basic-service-object-code-template.md)
+- [Creating a Service Object Sample](creating-a-service-object-sample.md)
+
+#### Concepts
+
+- [Attributes for Identifying Service Objects and Assigning Hardware](attributes-for-identifying-service-objects-and-assigning-hardware.md)
+- [Plug and Play XML Configuration](plug-and-play-xml-configuration.md)
+
+#### Other Resources
+
+- [Service Object Samples: Getting Started](service-object-samples-getting-started.md)
+- [POS for .NET Service Object Architecture](pos-for-net-service-object-architecture.md)

docs/framework/additional-apis/pos-for-net/asynchronous-output-sample.md

@@ -0,0 +1,161 @@
+---
+title: Asynchronous Output Sample
+description: Asynchronous Output Sample (POS for .NET v1.14 SDK Documentation)
+ms.date: 03/03/2014
+ms.topic: how-to
+ms.custom: pos-restored-from-archive
+---
+
+# Asynchronous Output Sample (POS for .NET v1.14 SDK Documentation)
+
+Microsoft Point of Service for .NET (POS for .NET) supports asynchronous output in compliance with the Unified Point Of Service (UnifiedPOS) specification. In the asynchronous output model, the Service Object must queue output requests so that it can return control to the application as quickly as possible. A second thread must then dispatch output to the device and notify applications when the request has been fulfilled, either with an **OutputCompleteEvent** or an **ErrorEvent** event.
+
+The POS for .NET class library handles most of these functions for the Service Object developer so that there is little, if any, difference between an asynchronous output device and a synchronous output only device.
+
+## To create the project
+
+1. Create a Visual Studio class library project.
+
+2. Add the sample code below to your project.
+
+3. Add references to the **Microsoft.PointOfService** assemblies.
+
+4. Compile and copy the Service Object to one of the directories in your Service Object assembly load path.
+
+## To use the application sample with the Service Object
+
+- This Service Object can be used with the application sample presented in [Event Handler Sample](event-handler-sample.md).
+
+## Example
+
+To output to a **PosPrinter** device, an application will most commonly use the <xref:Microsoft.PointOfService.BaseServiceObjects.PosPrinterBase.PrintNormal(Microsoft.PointOfService.PrinterStation,System.String)> method. Notice that the **PosPrinter** Service Object code below does not provide an implementation for this method. Instead, <xref:Microsoft.PointOfService.BaseServiceObjects.PosPrinterBase.PrintNormalImpl(Microsoft.PointOfService.PrinterStation,Microsoft.PointOfService.BaseServiceObjects.PrinterState,System.String)> is implemented. This method is called by the POS for .NET library for both synchronous and asynchronous output requests.
+
+When an application calls an output method, such as **PrintNormal**, the POS for .NET implementation checks the value of the <xref:Microsoft.PointOfService.PosPrinter.AsyncMode> property. If this value is **false**, then the POS for .NET library sends the request to **PrintNormalImpl** immediately and waits for it to return. If the value is **true**, however, then the POS for .NET implementation of **PrintNormal** adds the request to an internally managed queue. While there are items in the queue, a POS for .NET managed thread will send each request, in first-in-first-out (FIFO) order, to the device by calling **PrintNormalImpl**. When **PrintNormalImpl** returns, the library implementation will raise an <xref:Microsoft.PointOfService.PosPrinter.OutputCompleteEvent> in the application. In short, the same Service Object code can support both synchronous and asynchronous output without ever needing to know which output mode is being used.
+
+```csharp
+using System;
+using System.Collections.Generic;
+using System.Text;
+using System.Threading;
+using Microsoft.PointOfService;
+using Microsoft.PointOfService.BaseServiceObjects;
+
+[assembly: PosAssembly("Service Object Contractors, Inc.")]
+
+namespace SOSamples.AsyncOutput
+{
+    [ServiceObject(
+            DeviceType.PosPrinter,
+            "AsyncOutputPrinter",
+            "Sample Async Printer",
+            1,
+            9)]
+
+    public class AsyncOutputSimulator : PosPrinterBase
+    {
+        public AsyncOutputSimulator()
+        {
+            DevicePath = "Sample Async Printer";
+
+            // Indicate that the Service Object supports
+            // the receipt printer.
+            Properties.CapRecPresent = true;
+        }
+
+        // Note that this method will be called by the POS for .NET
+        // library code, regardless of whether the print request
+        // is synchronous or asynchronous. The print request
+        // queue is managed completely by POS for .NET so the
+        // Service Object should simply write data to the device
+        // here.
+        protected override PrintResults PrintNormalImpl(
+                        PrinterStation station,
+                        PrinterState printerState,
+                        string data)
+        {
+            // Your code to print to the actual hardware would go
+            // here.
+
+            // For demonstration, however, the code simulates
+            // that fulfilling this print request took 4 seconds.
+            Thread.Sleep(4000);
+
+            PrintResults results = new PrintResults();
+            return results;
+        }
+
+        // This method must be implemented by the Service
+        // Object, and should validate the data to be printed,
+        // including any escape sequences. This method should throw
+        // a PosControlException to indicate failure.
+        protected override void ValidateDataImpl(
+                        PrinterStation station,
+                        string data)
+        {
+            // Insert your validation code here.
+            return;
+        }
+
+        #region Implement Abstract PosCommon Members
+        private string MyHealthText = "";
+
+        // PosCommon.CheckHealthText.
+        public override string CheckHealthText
+        {
+            get
+            {
+                // VerifyState(mustBeClaimed,
+                // mustBeEnabled).
+                VerifyState(false, false);
+                return MyHealthText;
+            }
+        }
+
+        //  PosCommon.CheckHealth.
+        public override string CheckHealth(
+                        HealthCheckLevel level)
+        {
+            // Verify that device is open, claimed, and enabled.
+            VerifyState(true, true);
+
+            // Insert your code here:
+            // check the health of the device and return a
+            // descriptive string.
+
+            // Cache result in the CheckHealthText property.
+            MyHealthText = "Ok";
+            return MyHealthText;
+        }
+
+        // PosCommon.DirectIOData.
+        public override DirectIOData DirectIO(
+                                int command,
+                                int data,
+                                object obj)
+        {
+            // Verify that the device is open.
+            VerifyState(false, false);
+
+            return new DirectIOData(data, obj);
+        }
+        #endregion Implement Abstract PosCommon Members
+    }
+}
+```
+
+The application code in the [Event Handler Sample](event-handler-sample.md) can be compiled and run with this Service Object.
+
+## See Also
+
+#### Tasks
+
+- [Event Handler Sample](event-handler-sample.md)
+
+#### Concepts
+
+- [Event Management](event-management.md)
+- [Device Output Models](device-output-models.md)
+
+#### Other Resources
+
+- [Developing a Custom Service Object](developing-a-custom-service-object.md)

docs/framework/additional-apis/pos-for-net/attributes-for-identifying-service-objects-and-assigning-hardware.md

@@ -0,0 +1,39 @@
+---
+title: Attributes for Identifying Service Objects and Assigning Hardware
+description: Attributes for Identifying Service Objects and Assigning Hardware (POS for .NET v1.14 SDK Documentation)
+ms.date: 02/27/2008
+ms.topic: how-to
+ms.custom: pos-restored-from-archive
+---
+
+# Attributes for Identifying Service Objects and Assigning Hardware (POS for .NET v1.14 SDK Documentation)
+
+POS for .NET uses .NET reflection and .NET attributes to locate Service Object assemblies, identify Service Objects within those assemblies, and finally to associate a Plug and Play device with that Service Object. By leveraging these .NET features, <xref:Microsoft.PointOfService.PosExplorer> can identify Service Objects within an assembly and quickly assess their Plug and Play requirements. The expensive process of loading a .NET assembly is delayed until needed by the application.
+
+In order to provide these features, POS for .NET depends on three different .NET attributes:
+
+- **PosAssembly**
+    This is a global, assembly-level attribute that tells **PosExplorer** that this is a POS for .NET assembly which contains one or more Service Objects. Generally, it should be set in your **AssemblyInfo.cs** source file. For an example, see [Setting up a Service Object Project](setting-up-a-service-object-project.md).
+- **ServiceObject**
+    This attribute is applied to the Service Object class and specifies the type, name, and version information for the Service Object. See the [Creating a Basic Service Object Code Template](creating-a-basic-service-object-code-template.md) section for an example.
+- **HardwareId**
+    This attribute is used to specify which hardware IDs will be used by this Service Object. This information is used by **PosExplorer** to filter out Service Objects that use Plug and Play hardware which is not currently plugged in. The **HardwareId** attribute allows multiples, so there may be several attached to a Server Object class. See the sample topic [Adding Plug and Play Support](adding-plug-and-play-support.md) for an example. For a more lengthy discussion of Plug and Play features, including how the **HardwareId** attribute is utilized, see the topics [Adding Plug and Play Support](adding-plug-and-play-support.md) and POS for .NET [POS for .NET Integration with Plug and Play](pos-for-net-integration-with-plug-and-play.md).
+
+## See Also
+
+#### Reference
+
+- <xref:Microsoft.PointOfService.PosAssemblyAttribute>
+- <xref:Microsoft.PointOfService.HardwareIdAttribute>
+- <xref:Microsoft.PointOfService.ServiceObjectAttribute>
+
+#### Concepts
+
+- [Plug and Play Support](plug-and-play-support.md)
+- [POS for .NET Registry Settings](pos-for-net-registry-settings.md)
+
+#### Other Resources
+
+- [POS for .NET Service Object Architecture](pos-for-net-service-object-architecture.md)
+- [System Configuration](system-configuration.md)
+- [Service Object Samples: Getting Started](service-object-samples-getting-started.md)

docs/framework/additional-apis/pos-for-net/base-class-directio-method.md

@@ -0,0 +1,31 @@
+---
+title: Base Class DirectIO Method
+description: Base Class DirectIO Method (POS for .NET v1.14 SDK Documentation)
+ms.date: 03/03/2014
+ms.topic: how-to
+ms.custom: pos-restored-from-archive
+---
+
+# Base Class DirectIO Method (POS for .NET v1.14 SDK Documentation)
+
+The **DirectIO** method and the **DirectIOEvent** event are used to provide functionality to the application that is not otherwise supported by the standard Unified Point Of Service (UnifiedPOS) specification for a particular device type.
+
+## DirectIO Method
+
+If a device has features that are not supported by the standard UnifiedPOS specification, a Service Object may implement a **DirectIO** method to give the application access to those features.
+
+An example might be a **LineDisplay** device that supports multicolor output. Few, if any, **LineDisplay**-type devices support color output, but an independent hardware vendor (IHV) might produce such a device and want to have the new features available to applications.
+
+Use of this method will make the application nonportable, since the implementation of the **DirectIO** method is vendor-specific. An application that uses a **DirectIO** method on Vendor A's **LineDisplay** device cannot depend on using a Vendor B's device.
+
+### DirectIOEvent
+
+This event can be used to send vendor-specific information directly to the application. This event provides a means for a vendor-specific UnifiedPOS service to provide events to the application that are not otherwise supported by the UnifiedPOS control.
+
+Using this event will make an application incompatible with devices from other vendors.
+
+## See Also
+
+#### Other Resources
+
+- [Developing Service Objects Using Base Classes](developing-service-objects-using-base-classes.md)

docs/framework/additional-apis/pos-for-net/capability-properties.md

@@ -0,0 +1,35 @@
+---
+title: Capability Properties
+description: Capability Properties (POS for .NET v1.14 SDK Documentation)
+ms.date: 03/03/2014
+ms.topic: how-to
+ms.custom: pos-restored-from-archive
+---
+
+# Capability Properties (POS for .NET v1.14 SDK Documentation)
+
+Certain properties cannot be set directly within a Service Object. This comes up most often in the case of capability properties; those with the **Cap** prefix in their names. According to the Unified Point Of Service (UnifiedPOS) specification, these properties must be read-only; therefore, an implementation-specific mechanism is needed for the Service Object to change the value of these properties.
+
+## BaseClass Properties
+
+Microsoft Point of Service for .NET (POS for .NET) **Base** classes have a protected property, **Properties**, for this purpose. This property returns a helper class which has writable versions of the read-only properties implemented in the **Base** class. For example, <xref:Microsoft.PointOfService.BaseServiceObjects.PinPadBase> has a property called <xref:Microsoft.PointOfService.BaseServiceObjects.PinPadBase.Properties> that returns an object of type <xref:Microsoft.PointOfService.BaseServiceObjects.PinPadProperties>. And this object contains properties used to set various **PinPad**-specific capability properties, such as <xref:Microsoft.PointOfService.PinPad.CapDisplay>.
+
+## PosCommon Properties
+
+In addition to device-specific property classes, all POS for .NET **Base** and **Basic** classes also have a protected property called **CommonProperties** which returns an object of type **CommonProperties**. This helper class is used to modify capability and status properties found in **PosCommon**.
+
+## Setting Properties Using Helper Classes
+
+In general, a Service Object should always access the value of its common and class-specific properties using the helper classes. These properties may be written to by the Service Object and always contain the appropriate values.
+
+The Service Object developer should be aware of what the POS for .NET framework may do when a particular value is changed. For example, the Service Object should generally not change **CommonProperties.State** since this may interfere with the POS for .NET internal state. Similarly, the Service Object developer should be aware that changing **CommonProperties.PowerState** may send a **StatusUpdateEvent** event to the application.
+
+> [!NOTE]
+> When deriving from the POS for .NET **Base** or **Basic** classes, the Service Object should generally not change the value of **CommonProperties.State** to **ControlState.Closed**. Doing so prevents cleanup of the event queue, and POS for .NET may later throw exceptions as it tries to process events already in the queue.
+
+## See Also
+
+#### Reference
+
+- <xref:Microsoft.PointOfService.BaseServiceObjects.PinPadProperties>
+- <xref:Microsoft.PointOfService.StatusUpdateEventHandler>