Novell is now a part of Micro Focus

Using Messaging APIs, Part II: SMF-71I

Articles and Tips: article

BRUCE GREENBLATT
Systems Architect
GroupWare Division

LARRY MORRIS
Senior Editor
Systems Research Department

01 Jul 1995


This is part 2 in a series of DevNotes on messaging APIs. Part 1 dealt with MAPI, CMC, and VIM. This article discusses Novell's SMF-71, a prominent file-format API. SMF is a set of rules governing how applications and gateways must construct messages to ensure reliable delivery by the messaging system. An SMF message is a text file that conforms to the SMF protocol. You submit an SMF message file for delivery by writing the SMF message file to a designated directory on a NetWare messaging server. SMF-71 enhancements over SMF-70 include the following: enhanced addressing support, unlimited number of message recipients, distribution list support, unlimited header size, optional To header, and additional notification headers. In addition, NetWare 4.1 has added objects to the NDS schema that have been designed specifically for messaging.

Previous DevNotes in This Series May/June 95 "Using Messaging APIs"

Introduction

Messaging APIs allow developers to build E-mail interfaces into a variety of applications. The two basic types of messaging APIs are file-format APIs and programmatic APIs. Part 1 of this two-part series (published in the May/June 1995 issue of Developer Notes) discussed the following programmatic APIs:

  • MAPI

  • VIM

  • CMC

This article discusses a prominent file-format API: Novell's SMF-71.

Defining SMF

SMF is a set of rules governing how applications and gateways must construct messages to ensure reliable delivery by the messaging system. (Messages are defined as units of information containing addresses, text, and attached files.) The current version of SMF is SMF-71, which is designed to be compatible with NetWare Directory Services (NDS). The previous version, SMF-70, was a simpler implementation limited by its 8-character addressing scheme (which is not compatible with NDS).

Observing SMF rules allows developers to ensure the reliability and interoperability of applications and gateways. SMF rules fall into three basic categories:

  • Message generation and management

  • Interaction between applications or gateways and MTAs

  • Interaction between one application or gateway and another application or gateway

Messages are transferred by message transfer agents (MTAs). (MTAs, UAs [users agents], and other components of an E-mail system are defined in X.400, the ITU standard for E-mail and messaging.) An SMF-compatible MTA is a program that transfers messages from an SMF-compatible application or gateway to applications or gateways that are compatible with NetWare MHS and NetWare NMS.

The SMF-compatible MTAs transfer messages between SMF and other messaging environments, including those that use non-SMF message and address formats. MTAs can transfer messages across a broad range of data communications media, such as telephone lines, Ethernet, and wide area networks.

Novell provides the following SMF-compatible MTAs:

  • NetWare MHS 1.5, a DOS-based MTA.

  • NetWare Global MHS, an MTA that runs as a set of NLMs on a NetWare server.

  • NetWare Basic MHS, an entry level MTA that is supplied with NetWare 3.12.

  • Messaging Services for NetWare 4.1, a full featured MTA that uses NDS as its messaging directory, and is supplied with NetWare 4.1.

Public hubs can also provide SMF-compatible MTAs on other platforms.

A key feature of SMF is its platform independence. A wide variety of applications (running on a wide variety of operating systems) can handle SMF files. Applications and gateways submit a message to an MTA by writing it to a designated directory. After a message is submitted, the MTA picks it up from that directory and routes it. Any application or gateway that can place an ASCII file in a directory can use an SMF-compatible MTA to deliver messages and files. The MTA handles all connectivity issues; it establishes modem settings, transfers messages according to the appropriate messaging protocol, and checks errors.

Message Construction and Submission

The SMF message format is file-based. An SMF message is a text file that conforms to the SMF protocol. You submit an SMF message file for delivery by writing the SMF message file to a designated directory on a NetWare messaging server. Message pickup consists of reading an SMF message file from a designated directory on a NetWare messaging server. Thus, a message can be composed using a text editor and submitted or picked up by using file copy commands. Any application or gateway that can place an ASCII file in a directory can use a NetWare SMF-compatible MTA to route and transport messages and attached files.

Using any program that allows you to create an ASCII file, you can create an SMF message consisting of the following elements:

  • Envelope (ENV) headers that request the MTA to perform a specific action when delivering the message.

  • Interpersonal messaging (IPM) headers that are only used by SMF-compatible messaging applications. This includes OEM proprietary-use headers. An optional message body is included as part of the message.

Among the ENV headers are pointers to optional attached files. Attached files (also known as attachments) can contain any type of ASCII or binary information. SMF-71 allows multiple attachments. The optional attachments are separate files; each can contain any kind of ASCII or binary data, including, spreadsheets, text (including those generated by any word processor), graphics, databases, and executable program code.

Because SMF v71 is a file-based interface, a messaging application submits a message for delivery by writing it to a specific directory for message submission. If the message has attachments, the application simultaneously writes them to a directory for submission of attachments. The message and attachment directories are subdirectories of the NetWare messaging directory structure. SMF-71 applications interact with the MTAs through the SND, PARCEL and USERS directories.

NetWare Messaging Directory Structure

As Figure 1 shows, the \MHS directory is installed in the root directory and contains the following subdirectories:

  • EXE

  • SYS

  • SW

  • MAIL

Figure 1: The MHS directory structure.

The \MHS\EXE directory includes key utilities (such as the Admin program described below) and NLMs. The \MHS\SYS directory contains documentation for MHS. The \MHS\SW directory is a swap directory. MHS stores messages here temporarily, while checking to make sure that those messages have been copied correctly.

The\MHS\MAIL\USERS directory includes a directory, or local mailbox, for each MHS user. The \MHS\MAIL\PUBLIC directory contains database and log records. The \MHS\MAIL\QUEUES directory is a holding area for both messages and attachments. The \MHS\MAIL\SND directory contains messages waiting to be delivered. (Files waiting to be delivered do not include an extension; undeliverable files have a .BAD extension.) The \MHS\MAIL\PARCEL directory temporarily stores attachments to messages. The \MHS\MAIL\GATES directory is used for gateways.

SMF applications interact with the MTAs through the SND, PARCEL, and USERS directories. Applications pick up messages from the mailboxes of individual users (which are in the subdirectories of \MHS\MAIL\USERS\username). Applications submit the main files of outgoing messages to \SND and associated attachments to \PARCEL.

SMF gateways exchange mesages through the gateway directories IN, IPARCEL, OUT, and OPARCEL. Each gateway is responsible for picking up messages from an external messaging system or program. The MTA automatically starts a program to import messages if the gateway chooses to supply one. Gateways running as an independent program on some other NetWare client workstation or as NLMs on the messaging server do not need to supply this program.

Message TransferAfter a message is submitted to the MTA, the MTA automatically picks it up, reads the header information, resolves the recipient's address, then either delivers the message locally or transfers the message to another MTA or a gateway that will deliver the message. The MTAs use a process called store-and-forward to transfer messages. Messages are stored in one location and then forwarded to another location until they reach their final destination. The MTA delivers messages as follows:

  • Local delivery. The MTA moves a message between a sender and a recipient who each have a mailbox on the same messaging server. Once the message has been delivered to the recipient's mailbox, the recipient must run an application to pick up the message and display it.

  • Remote delivery. If sender has a mailbox on one messaging server and the recipient has a mailbox on another, the MTA determines the route for the message and delivers it to the recipient's mailbox. If the MTA cannot reach the recipient's mailbox directly, it forwards the message to the next server enroute to the destination. This procedure continues until the message arrives at its final destination.

  • Gateway delivery. If the recipient has a mailbox on a messaging server that is accessible only through a gateway, the MTA delivers the message to the gateway en route to the destination. The MTA moves the message to the gateway by copying it to a specially designated spooling area. The MTA places the messages in the gateway's OUT directory and any attachments in the gateway's OPARCEL directory. The gateway is responsible for picking up messages from the spooling area and forwarding them to the destination messaging system or program. The MTA also picks up any messages that the gateway placed in the spooling area for delivery by the MTA. The MTA picks up messages from the gateway's IN directory and any attachments from the gateway's IPARCEL directory.

Message Pickup

When the message reaches the recipient's messaging server, the MTA uses the messaging directory database to identify the recipient and then writes the message and attachments to the inbound message and attachment subdirectories of the recipient's mailbox on that server. These subdirectories are appname (the actual name of this subdirectory is dependent upon the user's installed MHS application) and IPARCEL in the ...\MHS\MAIL\USERS\username directory. After the MTA delivers messages to a recipient's mailbox, the messaging application picks up the messages from the mailbox and processes them.

SMF/MHS Example

The following example shows how an MTA, in this case NetWare MHS, deals with SMF-compatible files.

An application creates an SMF-compatible file (with the filename 2D8DF488) and places it in the \MHS\MAIL\SND directory:

Volume in drive N is SYS

Volume Serial Number is F760-7CD9

Directory of N:\MHS\MAIL\SND

FLG         FLG     125      02-13-95     11:02a

2D8DF488            202      07-05-95     12:12p

           4 files(s)           592 bytes

                             53596160 bytes free

NetWare MHS, which scans the \MHS\MAIL\SND directory every few seconds, picks up the file and routes it to the recipient (whose address is found in the SMF file itself). To deliver the message, MHS assigns a new filename ($T000000) and places the file in the recipient's "mailbox," which is the \MHS\MAIL\USERS\ username\MHSdirectory:

Volume in drive N is SYS

Volume Serial Number is F760-7CD9

Directory of N:\MHS\MAIL\USERS\LMORRIS\MHS

FLG        FLG      0        02-13-95    11:05a

$T000000            494      07-05-95    12:18p

        4 files(s)                  770 bytes

                            53579776 bytes free

SMF Environment

The SMF environment consists of the following basic components:

  • SMF Messages, consisting of envelope (ENV) headers,interpersonal messaging (IPM) headers, text, and up to 64 attached files. The headers and message body are placed in a single file. Attached files are kept as separate files and can contain any kind of data, including ASCII, spreadsheet, print, or graphics files, word processor files, database entries, or executable program code.

  • Admin Program. Both MHS and MMS provide an ineractive admin program. Administrators can use the admin program to setup messaging servers; review, add, modify, or delete usernames; define the routing tables and affiliated workgroups; and manage applications that use the messaging system.

  • Messaging Server, which determines the routes for the SMF mesages, connects to a remote messaging server, exchanges messages through a gateway, and delivers messages locally.

The following utilities are available to assist in the development of applications and gateways:

  • MHSUSER. SMF-70 applications or gateways can use this command-line utility for administrative tasks.

  • SMFSEND. Applications can use this DOS utility to package and send messages in SMF format.

  • DIRADM. SMF-71 applications or gateways can use this utility to add usernames, workgroups, and Dlists in SMF-71 format.

Note: These tools are not available in Messaging Services for NetWare 4.1

New Features in SMF-71

SMF-71 enhancements over SMF-70 include the following:

  • Enhanced Addressing Support. SMF-71 address format supports user-friendly long names; the eight-character naming restrictions have been removed. Names can be a full name separated by spaces such as "EvelynNesbit" and "James M Howell"and the workgroup part can be expressed as a hierarchy such as "Sales.Aptos Corp" in an SMF-71 address. The total size of the SMF-71 address can be up to 253 characters. The character set permitted for addresses has been expanded to include spaces and additional useful characters.

  • Unlimited Number of Message Recipients. The SMF-71 format allows an unlimited number of message recipients in the address headers such as To, Copies-to, BCC, and Send-to.

  • Distribution List (DList) Support. SMF-71 compatibleMTAs provide a means for messaging administrators to associate a group of users into a DList. This provides application users with a convenient method of addressing a group of recipients. These DLists are automatically expanded by the MTA.

  • Unlimited Header Size. Size limitations for headers have been removed.

  • Optional To Header. The To header is no longer mandatory. However, an SMF-71 message submitted by a mail application must have at least one recipient header (To, Copies-to, BCC, or Send-to).

  • Additional Notification Headers. The following headers have been added to SMF-71 because notifications generated on both sides of SMF gateways might carry more information (regarding the reason for the notification) than the SMF headers Addresses-referred-to and Errors-to can handle: Delivered-to Delivery notification Exported-to Passage through a gateway that does not support delivery notification Notification-correlator Match message with notification Rejected-for Non-delivery notification Received-by Receipt-notification Refused-by Non-receipt-notification

  • Trace Headers. SMF-71 provides the following message headers that trace the routing path: Date-delivered Date-posted Date-received Date-transferred DL-expanded SMF-71 gateways generate an appropriate trace headers before submitting SMF-71 messages.

  • MHS\MAIL\PUBLIC\SMF_NS.XRT.SMF-71 applications can use the SMF Directory Service Extract file, SMF_NS.XRT, when they need read-only access to the messaging-directory database information. This file contains structured text information about all users and distribution lists (DLists) visible at a messaging server. Each user or DList has a fixed length record. The user records are sorted alphabetically by last name (not by SMF address).

  • Auto-forwarding. SMF-71-compatible MTAs support automatic forwarding of messages when the user accounts are appropriately configured. This allows users to direct the MTA to send messages to alternate recipients.

  • Third-party Document Translation. SMF-71-compatible MTAs have the ability to call third-party document translation NLMs (NetWare Loadable Modules) to convert attachments to the recipient's preferred format.

  • New-Mail Notifications. SMF-71-compatible MTAs can notify each logged-in users when new mail has arrived. This can be enabled on a per-server basis. If enabled, each user associated with a mailbox on that messaging server can disable this feature on an individual basis.

  • Sender Validation. This feature provides the ability to verify that a message was created by the user specified in the Sender header. The MTA validates messages submitted to the SND directory to ensure messaging system integrity.

SMF and NDS

Novell has added support for messaging applications to NetWare Directory Services (NDS). Version 4.1 of NetWare has added objects to the NDS schema that have been designed specifically for messaging. This version of MHS is called Messaging Services for NetWare 4.1 (also known as MHS Services). Some of the things SMF applications can do with NDS are:

  • Develop tightly integrated messaging applications and gateways

  • Get MHS Mailbox address from NDS

  • Add and delete users from NWAdmin

  • Get distribution list members from NDS

  • Get local users of an MHS MTA from NDS

  • Configure distribution lists and their members

NDS objects are identified by their distinguished names. MHS Services makes use of the NDS objects distinguished name in order to derive the objects email address as follows. Assume that some hypothetical user's distinguished name is: CN=Bob.OU=Marketing.O=Novell. In this situation, to generate the SMF-71 address from the NDS object name, convert the period between the CN and the other distinguished name components to the character '@'. Thus, Bob's email address would be: bob@marketing.novell.

In MHS Services, mail can be addressed to any of the following NDS Objects:

  • List Objects

  • GroupObjects

  • Organizational Role Objects

  • External Entity Objects

For more information about these object types, refer to the schema definition for version 4.1 of NDS.

The NetWare SMF-71 SDK

The NetWare SMF-71 SDK enables you to use SMF to create and test applications and gateways that take full advantage of the messaging services of NetWare Global MHS. If you already have NetWare Global MHS, you need purchase only the SMF-71 Programmer's Reference to develop SMF-compatible products.

The NetWare SMF-71 SDK consists of several components. Some of the components are provided on the NetWare SDK, Volume 3. Others, such as NetWare Global MHS and NetWare Remote MHS, described below, can be ordered for a nominal fee.

SMF-71 Programmer's Reference

Use the Dynatext SMF-71 Programmer's Reference Guide to become familiar with how to write messaging applications with SMF-71, which is a file-based applications programming interface (API).

Supplemental Information

Supplemental information is contained in directory \SMF71 on the CD. The following sections describe these files.

NetWare MHS MailSlotsNetWare MHS MailSlots (TM) is a set of MS Windows DLLs that enable your Windows applications to send and receive mail messages using NetWare MHS (TM). NetWare MHS MailSlots supports the following industry standard messaging APIs for NetWare MHS:

  • Common Messaging Call API (CMC)

  • Simple Messaging API (SMAPI)

  • Vendor Independent Messaging API (VIM)

Programming documentation is provided on Dynatext, while the product can be installed from \SMF71\MAILSLOT\PRODUCT\SETUP.EXE.

Simple MAPINetWare MHS MailSlots provides support for Simple MAPI (SMAPI) applications. However, keep in mind that SMAPI has been superceded by Common Messaging Call (CMC) as the preferred API for simple messaging needs. Newly developed applications with simple messaging requirements should use be written to use CMC instead of SMAPI.

SMF-71 Application Notes

After reading the SMF-71 Programmer's Reference, look through the SMF-71 Applications Notes document to review enhancements and clarifications to the SMF API. The information in this document supercedes information in the SMF-71 Programmer's Reference. To print this file to a postscript printer, print file \SMF71\MISCDOC\CLARIFY.PS.

Developing Messaging and GroupWare Applications for NDS

Application developers should begin to architect how their applications should integrate with NetWare 4 Directory Services.

Messaging and groupware developers should also architect how their applications will interact with MHS Services for NetWare 4, which ships with NetWare 4.1.

For information on how to integrate NetWare MHS messaging and groupware applications with DS, print file \SMF71\NW4SDK\DOC\ NW4SDK.PS to a postscript printer. For a sample code listing, print file \SMF71\NW4SDK\DOC\NW4CODE.PS to a postscript printer.

NetWare Remote MHS SDKVirtually any messaging application can be optimized for remote operation by providing a simple interface to Novell's Remote MHS product. This component provides all the functionality to make your application switch seamlessly between remote and network operation by allowing the application to view both environments as if they were identical.

A description of the application interface to Remote MHS is provided in the file TOOLKIT.TXT located in the directory \SMF71\MISCDOC\REMOTE.TXT.

Note: Remote MHS does not work with Messaging Services for NetWare 4.1.

Calendaring and Scheduling Interoperability

Use the MHS Alliance CSIP document to become familiar with how to write calendaring and scheduling applications that are interoperable with other CSIP applications.

Test Messages

The MHS Alliance, which is a consortium of NetWare MHS ISVs, has published a specification which tests for minimal compliance in interoperability between NetWare MHS applications.

Requirements for the SMF-71 SDK

The following sections list the hardware and software requirements for running the SMF-71 SDK.

Hardware. The NetWare server requires the following hardware:

  • 80386 or higher PC

  • 8MB total server RAM (minimum)

  • Additional disk space for storing messages.

Server Software. NetWare 2, 3, or 4 NOS

Client Software. Software to enable direct file access Any language capable of reading/writing formatted text and files

To order the SMF-71 SDK call 800-NETWARE (800-638-9273) in the U.S. and Canada. Elsewhere, call 801-429-5588.

The NetWare SMF-71 Software Developer's Kit for MHS (part number 884-000053-002) includes the following:

  • SMF-71 Programmer's Reference

  • Two copies of NetWare Global MHS, for use in testing your SMF-71 applications and gateways

Useful References

The following are references that you may find helpful to use with the SMF-71 SDK.

  1. SMF 71 SDK Addendum: NetWare 4 Integration. Available in Volume 3 of Novell Software Developer's Kits.

  2. SMF-71 SDK Addendum: Sample C Source Code for NetWare 4 Integration. Available in Volume 3 of Novell Software Developer's Kits.

  3. Novell SMF-71 Programmer's Reference Software Developer's Kit. Part Number 100-001213-001. Also available in Volume 3 of Novell Software Developer's Kits.

* Originally published in Novell AppNotes

Disclaimer

The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.

© Copyright Micro Focus or one of its affiliates