OSI/MHS Gateway Programmatic Interface (GPI) Reference Manual

Introduction to the GPI
OSI/MHS Gateway Programmatic Interface (GPI) Reference Manual—522223-001
1-4
Object Management
The GPI assigns a session identifier that you specify when creating or transferring a
communication. The GPI uses the session identifier to associate the communication
with the session performing the operation.
The GPI_OPEN_ procedure returns information about the local environment, including
the name of the management domain (MD) of the local MTA and the country of the MD.
For a detailed description, see MH-C-ENVIRONMENT
on page 3-19.
Each session is supported by a server called the Gateway Interface Process (GIP).
When a session is established, the GPI connects the session to an available GIP. The
GIPs are configured as a group and managed by the MHS manager process.
To end a session, you call the GPI_CLOSE_ procedure.
Object Management
An object is a set of attributes that characterize all or part of an X.400 communication.
For example, the attributes of a report include its content, descriptions of recipients, and
tracing information about its path through the network. A communication is called a
root object. An object can have an attribute that is itself an object, which is called a
subobject. For example, the attribute specifying the content of a message is a
subobject. You can transfer only root objects to and from the GPI service queues.
Objects are described in detail in Section 3, Object Classes and Attribute Types
.
Within a session, you manage inbound and outbound X.400 communications by using
the GPI object management procedures. A client program receives inbound
communications and sends outbound communications. These procedures enable you to
examine the attributes of inbound objects and to create outbound objects.
You can create a new object by using the GPI_OM_CREATE_ procedure, and you can
insert attributes into the object by using the GPI_OM_INSERT_ procedure. The
GPI_OM_WRITE_ procedure enables you to write a string one segment at a time, using
sequential calls. You can remove an attribute’s values by calling the
GPI_OM_REMOVE_ procedure.
When interpreting an inbound object, you can do the following:
•
Identify what types of attributes are present by using the GPI_OM_EXAMINE_
procedure. You can also use this procedure to retrieve the values of single-valued
attributes. Single-valued attributes can have only one value; multivalued attributes
can have multiple values. For example, a message’s content attribute can have only
one value, but its recipient-descriptors attribute can have multiple values.
•
Determine whether specific attributes are present by using the GPI_OM_FETCH_
procedure and, optionally, retrieve their values.
•
Retrieve the values of multivalued attributes by using the GPI_OM_LIST_
procedure.
•
Retrieve a string one segment at a time by using sequential calls to
GPI_OM_READ_. This procedure is typically used for very long string values.
You can copy an object and its subobjects by using the GPI_OM_COPY_ procedure,
and you can delete an object by using the GPI_OM_DELETE_ procedure.