Click or drag to resize

GS1.EPC.Api Namespace

This is the API package for the Electronic Product Code (EPC) Translator Library. Through this package, an application may convert between various forms of EPC data that occur in bar codes and RFID Tags.

The EPC Translator Library is organized around five main classes, depicted as the yellow boxes in the diagram below.

Since version 2.0 of the EPC Translator Library, the underlying data conversions are performed by a native library written in C. An additional class, Gs1EpcLib, has been provided to give access to the underlying data conversion functions.

The five main classes are:

  • Gs1ElementString   Represents a GS1 Element String, which is an ordered list of data elements from the GS1 Application Identifier (AI) data system. A GS1 Element String corresponds directly to data that is contained in GS1 bar codes.
  • Epc   Represents a GS1 Electronic Product Code (EPC), which is one of several specific GS1 Application Identifiers that can be used to identify a specific physical object.
  • RfidBank01   Represents the contents of memory bank 01 of a GS1 Gen2 or ISO/IEC 18000-6C RFID tag. When used in an EPC application, this memory bank contains an encoded representation of an EPC. When used in an ISO application, this memory bank contains Unique Item Identifier (UII) whose syntax is indicated by an Application Family Identifier (AFI).
  • RfidUserBank   Represents the contents of user memory (bank 11) of a GS1 Gen2 or ISO/IEC 18000-6C RFID tag, or the contents of any other type of RFID tag whose content encoding conforms to ISO/IEC 15962. The contents of the user memory bank consists of a set of data elements, where each data element includes an ISO Object Identifier (OID) that names the data element within a particular data system, and the value for the data element. When converted from a GS1 Element String, the data elements in a user bank are GS1 Application Identifiers, but user memory may also contain data elements from other data systems.
  • RfidBank10   Represents the contents of memory bank 10 of a GS1 Gen2 or ISO/IEC 18000-6C RFID tag, also known as the TID memory bank. This memory bank contains information about the RFID chip itself, such as the make and model. It may optionally contain additional information about tag capabilities, and/or a manufacturer-assigned serial number.
For EPC applications, all five classes are potentially relevant. For ISO applications, only the RfidBank01, RfidUserBank, and RfidBank10 classes will be relevant, and only those methods that do not deal specifically with GS1 data.

The diagram shows the available conversions between these classes, and the conversions to and from external forms (shown in red) including strings, URIs, binary, hexadecimal, etc.

The primary methods of these classes are organized as follows:

  • An instance of a class is constructed from one of the external forms by calling a static method of the class whose name begins with From. For example, Epc.FromEpcUri() constructs an Epc instance from the corresponding EPC Pure Identity URI.
  • A class instance may be converted to one of the external forms by referencing a property of the class. For example, the EPC Pure Identity URI for an Epc instance may be obtained from the EpcUri property of that class.
  • An instance of one class may be converted to an instance of another class by calling a method of the first class whose name begins with To. For example, an Epc instance may be converted to a Gs1ElementString by calling the ToGs1ElementString method. In some cases, converting from one class to another may require additional information. For example, an Epc instance may be converted to an RfidBank01 by calling the ToRfidBank01 method; this method takes additional arguments to specify the EPC Binary Encoding Scheme and filter value.
  • Some classes have additional properties for extracting components or performing other operations. For example, the EPC scheme of an Epc instance may be obtained by referencing the EpcScheme property.

A typical usage pattern is to convert between equivalent forms of a class by first calling a From method of that class, then referencing a property. For example, the following code converts the hexadecimal contents of EPC memory of an RFID tag into an EPC Tag URI:

C#
{
    String hex = "303531EDE4424C8000001ABF";
    RfidBank01 rfid = RfidBank01.FromEpcHex(hex);
    String tagUri = rfid.TagUri;
}
Conversely, the following example parses an EPC Tag URI and extracts the corresponding binary contents of RFID EPC memory, in 16-bit words:
C#
{
    String tagUri = "urn:epc:tag:sgtin-96:1.5012345.067890.6847";
    RfidBank01 rfid = RfidBank01.FromTagOrRawUri(tagUri);
    ushort[] words = rfid.EpcWords;
}

Another typical usage pattern is to create one class instance using a From method of that class, convert to a different class using a To method of that class (or a chain of such methods), then reference a property to extract the final external form. For example, the following code converts the hexadecimal contents of EPC memory of an RFID tag into the EPC Pure Identity URI:

C#
{
    String hex = "303531EDE4424C8000001ABF";
    RfidBank01 rfid = RfidBank01.FromEpcHex(hex);
    Epc epc = rfid.ToEpc();
    String epcUri = epc.EpcUri;
}
The following example converts the hexadecimal contents of EPC memory of an RFID tag into a string suitable for creating a bar code:
C#
{
    String hex = "303531EDE4424C8000001ABF";
    RfidBank01 rfid = RfidBank01.FromEpcHex(hex);
    Epc epc = rfid.ToEpc();
    Gs1ElementString es = epc.ToGs1ElementString();
    String barCode = es.BarCodeCharacters;
}
The following example converts a GTIN and serial number read from a bar code to the corresponding EPC URI:
C#
{
    String barCode = "0105012345678900216847";
    Gs1ElementString es = Gs1ElementString.FromBarCodeCharacters(barCode);
    int companyPrefixLength = 7;
    Epc epc = es.ToEpc(companyPrefixLength);
    String epcUri = EpcUri;
}
The following example converts a GTIN and serial number read from a bar code to an RFID SGTIN-96 with filter value 1, expressed in hexadecimal:
C#
{
    String barCode = "0105012345678900216847";
    Gs1ElementString es = Gs1ElementString.FromBarCodeCharacters(barCode);

    int companyPrefixLength = 7;
    Epc epc = es.ToEpc(companyPrefixLength);

    int filter = 1;
    RfidBank01 rfid = epc.ToRfidBank01(EpcTagScheme.SGTIN_96, filter);
    String hex = rfid.EpcHex;
}
The following example converts a GTIN, serial number, and batch/lot number read from a bar code to bytes suitable for programming into an RFID tag. The GTIN and serial number are encoded into the EPC memory bank using the SGTIN-96 encoding with filter value 1. The batch/lot number is encoded into user memory.
C#
{
    String barCode = "0105012345678900216847\x001D10ABC123";
    Gs1ElementString es = Gs1ElementString.FromBarCodeCharacters(barCode);

    int companyPrefixLength = 7;
    Epc epc = es.ToEpc(companyPrefixLength);

    int filter = 1;
    RfidBank01 rfidEpc = epc.ToRfidBank01(EpcTagScheme.SGTIN_96, filter);
    sbyte[] epcBytes = rfidEpc.EpcBytes;

    RfidUserBank rfidUser = es.ToRfidUserBank(false);
    sbyte[] userBytes = rfidUser.Bytes;
}
The following example converts a Digital Link URI containing a GTIN, serial number and batch/lot number into bytes suitable for programming into an RFID tag. By using the SGTIN+ tag scheme, all the data is encoded into the EPC memory bank.
C#
{
   String digitalLink = "https://example.com/01/80614141123458/10/10MD1234/21/223372036854"

   int filter = 1;
   RfidBank01 rfidEpc = RfidBank01.FromDigitalLink(digitalLink, "sgtin+", filter);
   sbyte[] = epcBytes = rfidEpc.EpcBytes;
}

Classes
 ClassDescription
Public classEpc An electronic product code (EPC). Instances of this class represent just the pure EPC identifier, without data carrier-specific control information such as filter bits.
Public classEpcClass An electronic product code (EPC) "class". An EPC Class is an identifier for objects that do not have individual instances identified. An EPC can be constructed from an EPC Class by adding a serial number.
Public classEpcClassScheme An EPC class scheme. This includes a scheme for each EPC pure identity scheme that can be used as an EPC class, along with schemes defined only as EPC class schemes.
Public classEpcException General exception for conditions related to the translation of Electronic Product Codes (EPCs).
Public classEpcLibException Base class for all checked exceptions thrown by the EPC Translator Library.
Public classEpcPattern An electronic product code (EPC) pattern. Instances of this class represent a set of EPCs.
Public classEpcScheme An EPC pure identity scheme.
Public classEpcTagScheme An EPC tag URI scheme.
Public classGs1Ai A GS1 Application Identifier and value, representing a specific data element that can be encoded into EPC data carriers according to GS1 standards.
Public classGs1ElementString A GS1 Element String, which is an ordered list of GS1 Application Identifiers (AIs), each of which is a specific data element. A GS1 Element string is an abstract representation of the application data content of a bar code or RFID tag conforming to GS1 standards.

In the bar code representation of GS1 Element String data, the order of AIs must conform to certain rules, namely that certain AIs of pre-defined size (as specified in the GS1 General Specifications) must occur first. The BarCodeCharacters property rearranges the order of AIs as necessary to accomplish this.

In the RFID representation of GS1 Element String data, different AIs are written to different RFID memory banks. In particular, the RFID EPC bank may only contain one of the following AI combinations:
EPC SchemeAIs
SGTINGTIN (AI 01) + SERIAL (AI 21)
SSCCSSCC (AI 00)
SGLNGLN (AI 414), with or without GLN Extension (AI 254)
GRAIGRAI (AI 8003) that includes the optional serial number
GIAIGIAI (AI 8004)
GDTIGDTI (AI 253) that includes the optional serial number
GSRNGSRN-Recipient (AI 8018)
GSRNPGSRN-Provider (AI 8017)
CPICPID (AI 8010) + CPID SERIAL (AI 8011)
SGCNGCN (AI 255) that includes the optional serial number
GINCGINC (AI 401)
GSINGSIN (AI 402)
ITIPITIP (AI 8006) + SERIAL (AI 21)
All AIs may be written to the RFID User Memory bank. Therefore, if a GS1 Element String contains none of the above AI combinations, then it can only be converted to a RfidUserBank instance containing all of the AIs in the GS1 Element String. If a GS1 Element String contains exactly one of the above AI combinations, then that AI combination can be converted to an Epc instance, and the remaining AIs converted to a RfidUserBank instance. If a GS1 Element String contains two or more of the above AI combinations, then the application must specify which combination is to be converted to an Epc instance, with the remainder being converted to a RfidUserBank instance. The toEpc and toRfidUserBank methods take arguments that guide which AI(s) are to be converted to EPC form or User Memory form.

In addition, to convert one of the above AI combinations to an EPC the application must specify the number of digits in the GS1 Company Prefix embedded within the AI. The methods take an argument to provide this.

Public classGs1EpcLib Access to the functions provided by the C EPC Translator library.
Public classGs1Exception General exception for conditions related to the translation of GS1 element strings.
Public classGs1GcpLengthTable A GcpLengthTable populated from data published by GS1, or from any other publisher using the same XML file format. The format of the XML file is as follows:
             <GCPPrefixFormatList date="2016-03-23T16:55:00Z">
               <entry prefix="00" gcpLength="7"/>
               <entry prefix="011" gcpLength="8"/>
               <entry prefix="018" gcpLength="10"/>
               <entry prefix="019" gcpLength="7"/>
               ...
             </GCPPrefixFormatList>
             
At the time of this writing, the GCP published file is available at the URL http://www.gs1.org/gcp-length.
Public classOid An ISO Object Identifier (OID). OIDs are used to identify data elements in RFID user memory.
Public classPrefixGcpLengthTable A implementation of a GcpLengthTable based on mapping a prefix to a length. Clients can use this class when they want to manage their own GCP length mappings. To use GS1 published data, see Gs1GcpLengthTable

For example, given the following table:

             PrefixGcpLengthTable t = new PrefixGcpLengthTable();
             t.add("999", 7);
             t.add("9998", 10);
             t.add("99712345", 8);
             
Then the following shows various GCP lengths returned by the table.
             t.gcpLength("9994567890123") ==> 7
             t.gcpLength("9998567890123") ==> 10
             t.gcpLength("9971234567890") ==> 8
             t.gcpLength("9971299999999") ==> UnknownGcpLengthException
             

Public classRfidBank01 The contents of the EPC/UII Bank (MB01) of an EPCglobal Gen2 / ISO 18000-6C RFID tag.
Public classRfidUserBank Dummy class for RfidUserBank in EPC only library
Public classUiiException General exception for conditions related to the translation of ISO Unique Item Identification (UII).
Public classUnknownGcpLengthException Exception thrown from a GcpLengthTable instance when the GS1 Company Prefix length cannot be determined.
Public classUserDataElement A data element that may be encoded into user memory, from any data system. A data element is a name/value pair, where the name is an and the value is a string.
Public classUserMemoryException General exception for conditions related to the translation of user memory.
Interfaces
 InterfaceDescription
Public interfaceGcpLengthTable Infers the length of the GS1 Company Prefix for a specified GS1 key. Different implementations of this class may reference different data sources and use different methods to make the inference. Clients may implement this interface to create their own strategies for GCP length lookup. For a simple implementation that maps prefixes to GCP length, see PrefixGcpLengthTable To use GS1-provided GCP length data, see Gs1GcpLengthTable
Enumerations
 EnumerationDescription
Public enumerationGs1EpcLibEncodings Encoding options for TDS 2.0 variable length alpha numeric components
Public enumerationGs1EpcLibTagSchemes EPC Tag Schemes.