// Copyright 2019 The Chromium OS Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef LIBIPP_IPP_H_
#define LIBIPP_IPP_H_

// What is this?
// -------------
// General library for building and parsing IPP frames. IPP stands for Internet
// Printing Protocol and is defined in several documents. This implementation
// is based mainly on the following sources:
// * rfc8010
// * rfc8011
// * CUPS Implementation of IPP at https://www.cups.org/doc/spec-ipp.html
// * IPP registry at https://www.pwg.org/ipp/ipp-registrations.xml
// In general, all non-deprecated IPP Operations from rfc8011 and "CUPS
// Implementation of IPP" are implemented. Vast majority of attributes that can
// be returned by these operations are recognized.
//
// Header files
// ------------
// To use the library include only this header (ipp.h). It includes four other
// header files:
// * ipp_base.h - main types and classes, look there for more details
// * ipp_attribute.h, ipp_package.h - classes defines general frame structure
// * ipp_enums.h - enums corresponding to IPP enums and keywords
// * ipp_operations.h - classes representing IPP requests and responses
// * ipp_collections.h - structs corresponding to IPP attributes being
//   collections, i.e. consisting of other attributes.
//
// General assumptions
// -------------------
// * all entities are defined in ipp namespace
// * many functions/methods returns bool to signal success or error:
//   - true means success
//   - false means error
// * vast majority of defined enums and basic types has corresponding functions
//   converting between their values and corresponding string representations:
//   - std::string ToString(type v) - converts v to std::string based on its
//     type. If given value cannot be converted (e.g unknown enum value) it
//     returns empty string.
//   - bool FromString(const std::string& s, type* v) - parses string and try to
//     convert it to value of type "type". If successful, saves parsed value to
//     the parameter v and returns true. Otherwise, returns false and leave the
//     parameter v untouched.
//
// The most important classes
// --------------------------
// * Client class for building IPP requests and parsing IPP responses
// * Server class for parsing IPP requests and building IPP responses
// * Request_* classes from ipp_operations.h representing IPP requests
// * Response_* classes from ipp_operations.h representing IPP responses
// * Attribute, Collection, Group, Package are base classes with general API to
//   browse structure of IPP frame
//
// Examples
// --------
// * ask printer for printer-make-and-model with Get-Printer-Attributes
//
//   std::string url = "ipp://my.printer/ipp";
//   std::vector<uint8_t> frame, frame2;  // these are buffers for IPP frames
//
//   ipp::Request_Get_Printer_Attributes request;
//   request.operation_attributes.printer_uri.Set(url);
//
//   ipp::Client client;
//   client.BuildRequestFrom(&request);
//   client.WriteRequestFrameTo(frame);
//
//   // ... Now you have to send the content of frame as a payload in HTTP POST
//   // ... request with content-type set to application/ipp.
//   // ... Then you have to retrieve a payload from obtained HTTP response and
//   // ... save it to the buffer frame2. Remember to check for HTTP errors.
//
//   ipp::Response_Get_Printer_Attributes response;
//   if (!client.ReadResponseFrameFrom(frame2)) {
//     // parsing error, check client.GetErrorLog()
//     return false;
//   }
//   if (!client.ParseResponseAndSaveTo(&response)) {
//     // parsing error, check client.GetErrorLog()
//     return false;
//   }
//   auto & attribute = response.operation_attributes.printer_make_and_model;
//   if (attribute.GetState() != ipp::AttrState::set)
//     std::cout << "Not included in the response :(\n";
//   else
//     std::cout << attribute.Get().value << "\n";
//
//
// * use CUPS-Get-Printers to query server for list of printers:
//
//   ipp::Request_CUPS_Get_Printers rq;
//   rq.operation_attributes.requested_attributes.Set(
//       {ipp::E_requested_attributes::printer_description});
//   ipp::Client cl;
//   cl.BuildRequestFrom(&rq);
//   std::vector<uint8_t> frame;
//   cl.WriteRequestFrameTo(frame);
//
//   // ... Now you have to send the content of frame as a payload in HTTP POST
//   // ... request with content-type set to application/ipp.
//   // ... Then you have to retrieve a payload from obtained HTTP response and
//   // ... save it to the buffer frame2. Remember to check for HTTP errors.
//
//   std::vector<uint8_t> frame2; // contains IPP frame with response
//   ipp::Response_CUPS_Get_Printers rs;
//   if (cl.ReadResponseFrameFrom(frame2) && cl.ParseResponseAndSaveTo(&rs)) {
//     // success, but it is good to check error log anyway
//     // there may be some warnings about incorrect fields
//     for (auto & l: cl.GetErrorLog())
//       std::err << "WARNING: " << l.message << "\n";
//     if (rs.status_code == Status::successful_ok) {
//       // iterate over printers and print out print-name
//       for (size_t i = 0; i < rs.printer_attributes.Size(); ++i) {
//         std::cout << rs.printer_attributes[i].printer_name.Get().value;
//         std::cout << std::endl;
//       }
//     } else {
//       std::cerr << "server returned IPP code: ";
//       std::cerr << ipp::ToString(rs.status_code) << std::endl;
//     }
//   } else {
//     // error - cannot parse obtained frame
//     std::err << "ERROR: IPP response is incorrect and cannot be parsed:\n";
//     for (auto & l: cl.GetErrorLog())
//       std::err << " * " << l.message << "\n";
//   }
//
//
// * In ipp_test.cc in functions Test1()-Test9() you can find more examples how
//   to build IPP frame.
//
// Notes to examples
// -----------------
// * The following attributes from group operation-attributes are set
//   automatically, if not specified by hand:
//   - attributes-charset -> utf-8
//   - attributes-natural-language -> en-us
//   - status-message -> ToString(this->status_code) - only for Response.
// * The method GetErrorLog() from Client/Server may return non-empty vector
//   even when all functions returned true. The parser can recover from many
//   local errors in IPP frames and ignore some incorrect values. Information
//   about all these events are logged to this vector.
// * If an attribute didn't appear in a response or is not supposed to be
//   present in a request, his state is set to AttrState::unset. It is default
//   value. Methods Set(...) automatically switch attribute's state to
//   AttrState::set. Attribute's state can be set by hand with method
//   Attribute::SetState(...). Other possible values besides AttrState::set and
//   AttrState::unset are out-of-band values (see [rfc8010] and [rfc8011]).
// * If the parsed frame contains an attribute that is no present in the IPP
//   schema, a general "unknown" attribute is added to the package. Unknown
//   attributes behave as known ones, the only difference is that they do not
//   appear in predefined structs.
//
// Naming conventions
// ------------------
// C++ names of operations, groups, attributes, enums and keywords are copied
// from IPP specification. Characters '-' and '.' were replaced by '_'. Names
// of main entities are constructed as follows:
// * Operations: classes Request_(IPP name) and Response_(IPP name), eg.:
//   - Request_Print_Job -> a request Print-Job
//   - Response_CUPS_Get_Printers -> a response for a request CUPS-Get-Printers
// * Groups: fields defined in Request/Response Operation classes, eg.:
//   - operation_attributes -> operation-attributes
//   - job_attributes -> job-attributes
// * Attributes: fields defined in Groups or inside other Attributes, eg.:
//   - attributes_natural_language -> attributes-natural-language
//   - printer_uri -> printer-uri
// * Enums and Keywords: enums E_(IPP name), eg.:
//   - E_pdf_versions_supported -> keyword pdf-versions-supported
//   - E_finishings -> enum finishings
// * Values of Enums and Keywords: just (IPP name), eg.:
//   - E_pdf_versions_supported::adobe_1_4 -> a value adobe-1.4
//   - E_finishings::staple_top_right -> a value staple-top-right
// For C++ enums corresponding to IPP enums all elements has numerical values
// from IPP specification (may be casted to uint16_t to get assigned IPP value).

// look here for Attribute class
#include "ipp_attribute.h"

// look here for main classes: Client, Server, Request, Response
#include "ipp_base.h"

// these files are generated from IPP schema
#include "ipp_collections.h"
#include "ipp_enums.h"
#include "ipp_operations.h"

// look here for Package, Group and Collection classes
#include "ipp_package.h"

#endif  //  LIBIPP_IPP_H_