GT 3.9.3 Component Guide to Public Interfaces: C Common Libraries

Semantics and syntax of APIs

Programming Model Overview

[Description of the programming model here]

Internationalization Infrastructure

The Globus Toolkit C Common Library now has optional infrastructure support for internationalization, which is used by GridFTP and its dependencies (pre-ws authorization/authentication and XIO).

This means that user-presented strings are wrapped in a lookup function, which, if the globus_i18n module is installed, and the GLOBUS_I18N environment variable is set to "YES" will lookup the string in a resource bundle using ICU4C. If GLOBUS_I18N is set to "NO", or the globus_i18n module is not installed, or the string value cannot be found in the resource bundle, the default string (exactly what was being looked up) is returned.

Developer Information

There are two functions that are used for string lookup.

globus_common_i18n_get_string( globus_module_descriptor_t * module, char * key);

This is the preferred function--you supply a module descriptor and the string you want to look up.

globus_common_i18n_get_string_by_key( char * locale, char * resource_name, char * key);

This function is used if you have need for looking up a particular locale. A NULL value for locale will look up from the default locale.

Typically, one or more macros will be defined on a per-module basis that supply the module descriptor, to reduce clutter in the code. Within the toolkit, these are typically _???SL where ??? are some mnemonic for the module in question (for example _GCSL is defined for globus_common).

The resource bundles used for the string lookups are created using ICU4C (see IBM documentation on Resource Bundles).

Our resource bundles are very simple--they contain simply a set of keys and strings. The key is actually the string itself, hashed using the globus_hashtable_string_hash function, then converted to contain only invariant characters ( #!@[]^`{|}~ are converted to '_'). See globus_i18n_resource_init.c in the globus_i18n source for an example of creating keys.

globus-i18n-resource-init from the globus_i18n package will take a file of strings as its input, and output a text file ready to be made into a resource bundle using genrb from ICU4C.

Resource bundles must be installed in $GLOBUS_LOCATION/share/i18n/

Component API

[link to auto-genned API docs here]

Semantics and syntax of the WSDL

Protocol overview

[provide an overview of the protocol for the service]

Operations

[list and briefly describe each operation]

Resource properties

[list and briefly describe each resource property]

Faults

[list and briefly describe each fault]

Schema Definition

[link to the source files here]

Command-line tools

Click here to see a nice example of content describing a command-line tool
If there is more than one command-line tool, put bullets up top and copy these topics for each tool

[tool name] for [component name]

Tool description

[Description of the command-line tool here. ]

Command syntax

[list and describe command-line args here]

Limitations

[describe limitations of the tool here]

Overview of Graphical User Interface [gui name]

Overview of the purpose and functionality of the GUI

[say it here]

Command and options

[describe syntax for invoking the gui here]

Limitations

[describe limitations here]

Semantics and syntax of domain-specific interface

Interface introduction

[provide an overview of the purpose and structure of the domain-specific interface]

Syntax of the interface

[list and describe detailed information here]

Configuration interface

Configuration overview

[high-level characterization of the configuration options for the component here]

Syntax of the interface

[list and describe detailed config info here]

Environment variable interface

  • provide details on settings and effect of env var #1
  • ...
  • provide details on settings and effect of env var #n