Make printer's DNS-SD Service Names freely configurable

[efuss]

Introduce a configuration variable DNSSDServiceName which, if set, provides a template for the DNS-SD Service Name used to register a printer. In the string, the following placeholders are substituted:

• %n: the printer's name
• %i: the printer's info field
• %l: the printer's location field
• %m: the printer's make & model field
• %c: the server's name
• %%: a literal percent sign

If DNSSDServiceName is unset (the default), the existing behaviour is used.

[michaelrsweet]

OK, I really like this enhancement!

Some feedback (beyond the inline comments):

• Please see CONTRIBUTING.md - your code doesn't follow the style we use for the CUPS sources.
• I'd like to rename the directive to "DNSSDNameTemplate"

I will also add an issue tracking the ability to set the "printer-dns-sd-name" value for a printer separately (so this template would set the initial value and then you can tweak each printer's DNS-SD service name after the fact).

[michaelrsweet]

The normal coding style here would be to set the end pointer to "name + sizeof(name) - 1" to leave room for the NUL at the end.

Also, you might use "src", "dst", and "dstend" as variable names to make things clearer... :)

[michaelrsweet]

"while (*src && dst < dstend)"?

[michaelrsweet]

Maybe log a warning message for unknown substitution characters?

[michaelrsweet]

strlcpy isn't standard. cupsCopyString is the CUPS API that uses strlcpy or its equivalent. But the return value is the number of characters that would have been copied if there was infinite space - I usually do copy and then "q += strlen(q)".

[efuss]

Thanks for the quick reply!

- Please see CONTRIBUTING.md - your code doesn't follow the style we use for the CUPS sources.

I did of course read that but it doesn't say anything about coding style. So I tried to match what was there.

- I'd like to rename the directive to "DNSSDNameTemplate"

No objection.

The normal coding style here would be to set the end pointer to "name + sizeof(name) - 1" to leave room for the NUL at the end.

I thought of that but as is it made computing the space for strlcpy() easier.

Also, you might use "src", "dst", and "dstend" as variable names to make things clearer... :)

Probably. The code was more a PoC or a basis for discussion, especially which fields can be substituted and how the % escapes are named. Plus we quickly needed someting that did %n.

"while (*src && dst < dstend)"?

I did think of that, but who puts in the trailing \0 then?

Maybe log a warning message for unknown substitution characters?

Yes.

strlcpy isn't standard. cupsCopyString is the CUPS API that uses strlcpy or its equivalent.

I originally developed against 2.4.16, which used strlcpy() a lot.

But the return value is the number of characters that would have been copied if there was infinite space

As does strlcpy(), no?

I usually do copy and then "q += strlen(q)".

The code breaks out if strlcpy() can't copy everything.

[michaelrsweet]

Sorry, I should have referenced "DEVELOPING.md" which has the coding style stuff:

Coding Guidelines

Contributed source code must follow the guidelines below. While the examples
are for C and C++ source files, source code for other languages should conform
to the same guidelines as allowed by the language.

Source code comments provide the reference portion of the CUPS Programming
Manual, which is generated using the codedoc
software.

Copyright notice

If there are changes for a file, which contains copyright notice already
and the notice is not updated for the current year, update the year of copyright
notice to include the current year.

Only the following files must have copyright notice updated every year: README.md,
NOTICE, index.html.in, and header.html.in.

Source Files

All source files names must consist of lowercase ASCII letters, numbers, dash
("-"), underscore ("_"), and period (".") to ensure compatibility across
different filesystems. Source files containing functions have an extension of
".c" for C and ".cxx" for C++ source files. All other "include" files have an
extension of ".h". Tabs are set to 8 characters/columns.

Note: The ".cxx" extension is used because it is the only common C++ extension
between Linux®, macOS®, Unix®, and Windows®.

The top of each source file contains a header giving the purpose or nature of
the source file and the copyright and licensing notice:

/*
 * Description of file contents.
 *
 * Copyright © 2021-2023 by OpenPrinting
 *
 * Licensed under Apache License v2.0.  See the file "LICENSE" for more
 * information.
 */

Header Files

All public header files must include the "versioning.h" header file, or a header
that does so. Function declarations are then "decorated" with the correct
_CUPS_API_major_minor macro to define its availability based on the build
environment, for example:

extern int cupsDoThis(int foo, int bar) _CUPS_API_2_2;

Private API header files must be named with the suffix "-private", for example
the "cups.h" header file defines all of the public CUPS APIs while the
"cups-private.h" header file defines all of the private CUPS APIs as well.
Typically a private API header file will include the corresponding public API
header file.

Comments

All source code utilizes block comments within functions to describe the
operations being performed by a group of statements; avoid putting a comment
per line unless absolutely necessary, and then consider refactoring the code
so that it is not necessary. C source files can use either the block comment
format ("/* comment */") or the C99/C++ "//" comment format, with the block
comment format being preferred for multi-line comments:

/*
 * Clear the state array before we begin.  Make sure that every
 * element is set to `CUPS_STATE_IDLE`.
 */

 for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++)
   array[i] = CUPS_STATE_IDLE;

 // Wait for state changes on another thread...
 do
 {
   for (i = 0; i < (sizeof(array) / sizeof(sizeof(array[0])); i ++)
     if (array[i] != CUPS_STATE_IDLE)
       break;

   if (i == (sizeof(array) / sizeof(array[0])))
     sleep(1);
 } while (i == (sizeof(array) / sizeof(array[0])));

Indentation

All code blocks enclosed by brackets begin with the opening brace on a new
line. The code then follows starting on a new line after the brace and is
indented 2 spaces. The closing brace is then placed on a new line following
the code at the original indentation:

{
  int i; // Looping var

  // Process foobar values from 0 to 999...
  for (i = 0; i < 1000; i ++)
  {
    do_this(i);
    do_that(i);
  }
}

Single-line statements following "do", "else", "for", "if", and "while" are
indented 2 spaces as well. Blocks of code in a "switch" block are indented 4
spaces after each "case" and "default" case:

switch (array[i])
{
  case CUPS_STATE_IDLE :
      do_this(i);
      do_that(i);
      break;

  default :
      do_nothing(i);
      break;
}

Spacing

A space follows each reserved word such as if, while, etc. Spaces are not
inserted between a function name and the arguments in parenthesis.

Return Values

Parenthesis surround values returned from a function:

return (CUPS_STATE_IDLE);

Functions

Functions with a global scope have a lowercase prefix followed by capitalized
words, e.g., cupsDoThis, cupsDoThat, cupsDoSomethingElse, etc. Private
global functions begin with a leading underscore, e.g., _cupsDoThis,
_cupsDoThat, etc.

Functions with a local scope are declared static with lowercase names and
underscores between words, e.g., do_this, do_that, do_something_else, etc.

Each function begins with a comment header describing what the function does,
the possible input limits (if any), the possible output values (if any), and
any special information needed:

/*
 * 'do_this()' - Compute y = this(x).
 *
 * This function computes "this(x)" and returns the result. "x" must be
 * between 0.0 and 1.1.
 *
 * Notes: none.
 */

static float       // O - Inverse power value, 0.0 <= y <= 1.1
do_this(float x)   // I - Power value (0.0 <= x <= 1.1)
{
  ...
  return (y);
}

Return/output values are indicated using an "O" prefix, input values are
indicated using the "I" prefix, and values that are both input and output use
the "IO" prefix for the corresponding in-line comment.

The codedoc documentation generator also
understands some markdown syntax as well as the following special text in the
function description comment:

@deprecated@         - Marks the function as deprecated: not recommended
                       for new development and scheduled for removal.
@link name@          - Provides a hyperlink to the corresponding function
                       or type definition.
@since CUPS version@ - Marks the function as new in the specified version
                       of CUPS.
@private@            - Marks the function as private so it will not be
                       included in the documentation.

Variables

Variables with a global scope are capitalized, e.g., ThisVariable,
ThatVariable, ThisStateVariable, etc. Globals in CUPS libraries are either
part of the per-thread global values managed by the _cupsGlobals function
or are suitably protected for concurrent access. Global variables should be
replaced by function arguments whenever possible.

Variables with a local scope are lowercase with underscores between words,
e.g., this_variable, that_variable, etc. Any "local global" variables
shared by functions within a source file are declared static. As for global
variables, local static variables are suitably protected for concurrent access.

Each variable is declared on a separate line and is immediately followed by a
comment describing the variable:

int         ThisVariable;    // The current state of this
static int  that_variable;   // The current state of that

Types

All type names are lowercase with underscores between words and _t appended
to the end of the name, e.g., cups_this_type_t, cups_that_type_t, etc.
Type names start with a prefix, typically cups or the name of the program,
to avoid conflicts with system types. Private type names start with an
underscore, e.g., _cups_this_t, _cups_that_t, etc.

Each type has a comment immediately after the typedef:

typedef int cups_this_type_t;  // This type is for CUPS foobar options.

Structures

All structure names are lowercase with underscores between words and _s
appended to the end of the name, e.g., cups_this_s, cups_that_s, etc.
Structure names start with a prefix, typically cups or the name of the
program, to avoid conflicts with system types. Private structure names start
with an underscore, e.g., _cups_this_s, _cups_that_s, etc.

Each structure has a comment immediately after the struct and each member is
documented similar to the variable naming policy above:

struct cups_this_struct_s  // This structure is for CUPS foobar options.
{
  int this_member;         // Current state for this
  int that_member;         // Current state for that
};

Constants

All constant names are uppercase with underscores between words, e.g.,
CUPS_THIS_CONSTANT, CUPS_THAT_CONSTANT, etc. Constants begin with an
uppercase prefix, typically CUPS_ or the program or type name. Private
constants start with an underscore, e.g., _CUPS_THIS_CONSTANT,
_CUPS_THAT_CONSTANT, etc.

Typed enumerations should be used whenever possible to allow for type checking
by the compiler.

Comments immediately follow each constant:

typedef enum cups_tray_e  // Tray enumerations
{
  CUPS_TRAY_THIS,         // This tray
  CUPS_TRAY_THAT          // That tray
} cups_tray_t;