Requirements for Client Library

The client library is an API encapsulating sending and receiving structured, secure clinical messages.

It supplies a clean API that does not require detailed knowledge of the underlying implementation details of XD*, MIME, S/MIME, RFC 5322, and the like, but should allow for composition and "peeking into the package" for programers who want to get closer to the wire.

The ideal API will work somewhat like this:

using Health.Net.Direct;

var sender = new Address("arien.malec@nhin.example.org");
var receivers = from a
                in ["john.smith@nhin.example.org", "sally.jones@exchange.example.com", "jesus.walinsky@hie.example.org"]
                select new Address(a);

var message = new Message(sender, receivers);

message.TextMessage = File.ReadAllText("message.txt");

// The following automatically extract metadata
message.AddDocumentFromFile("clinical_summary.ccr");
message.AddDocumentFromFile("clinical_summary2.ccd");
message.AddDocumentFromFile("lab_oru_message.hl7");

//Manual addition of metadata
var document = new Document();
document.LoadFile("treatment_summary.pdf");
document.Author = new Author("Arien", "Malec");
message.AddDocument(document);

Metadata metadata = message.Metadata; // allows for getting/setting metadata properties

XMLDocument xds_metadata = metadata.ToXDSMetadata();

XDMZip xdmzip = message.ToXDM();

string outgoing_email = message.ToRfc5322(); // RFC 5322 email message with Base64 encoded XDM attachment

var client_config = new ClientConfiguration("config.xml");

var client = new Client(client_config);

client.Send(message);

// create Agent

var agent = new Agent();
OutgoingMessage outgoing = agent.ProcessOutgoing(message);

string incoming_msg = File.ReadAllText("incoming.eml");
var message2 = Message.CreateFromIncomingMessage(agent.ProcessIncoming(incoming_msg));
 

There's clearly a lot of magic going on here. I like magic in my APIs. I suggested, in Reference Implementation Components that we break this down to:

1. Metadata object and XD* reader/writers (the Direct.Metadata object)
2. Message object (provides a uniform interface for messages, regardless of the transmission method); can serialize/deserialize to XDM, RFC 5322 (email + MIME + XDM), XDR SOAP payload
3. XDR direct (XDD) and SMTP/IMAP handling (client.Send())
4. Metadata extractors (without that, you'd have to use the manual method shown above)