API
@-Formulas
JavaScript
LotusScript
Reg Exp
Web Design
Notes Client
XPages
 
Reading a MIME Entity in the C API
I don't claim to be the best C programmer out there, but I have written DLL's, Domino server add-in tasks, and other API programs. When I was working with MIME trying to track down an issue someone was having, I didn't find much documentation on the subject. So I thought I'd share some findings, both for my reader's benefit and my own future benefit.

I was writing a C program that would pull the text out of a document for manipulation. If the field being investigated is a rich text field, then the API function ConvertItemToText is used to grab the text. That function is pretty well documented and there are lots of examples to be found on the internet about its use. But if the field is a MIME field instead, it takes another approach to pull out the text, and that's where I wasn't able to find out too much.

First, you need to identify the type of field you're working with. That is done through the NSFItemInfo function. Here is some example code:

if (error = NSFItemInfo(hNote, "Body", (WORD)strlen("Body"), NULL, &fieldType, &fieldBlock, &fieldLen)) {
    return ERR(error);
}

The variable hNote is a NOTEHANDLE value pointing to the open document. fieldType is a WORD variable and is the type of field returned by the call (more on that in a minute). fieldBlock is a BLOCKID variable that will be used later to grab the data from the field. fieldLen is a DWORD variable that tells you the length of the value.

If the field type is TYPE_COMPOSITE, then it's a normal rich text field and you can pass fieldBlock and fieldLen to ConvertItemToText to pull out the text from the rich text item. But that isn't the point of this tip.

If the field type is TYPE_MIME_PART, then you're dealing with a MIME field. What you need to do is lock the memory, pull out the MIME information, and then the data is right after then "header" (not a MIME header, but an API structure header). First, the memory needs to be locked:

pMime = (MIME_PART *)OSLockBlock(MIME_PART, fieldBlock);

The variable pMime is a pointer to a MIME_PART structure, so it's defined like this:

MIME_PART *pMime;

The actual content of the MIME entity follows the structure pointed to by pMime. So define a character pointer that will be used to point to the data:

char *pText;

The pointer to the text is positioned after the MIME_PART structure:

pText = (char *)pMime + sizeof(MIME_PART);

Then, it's a matter of moving that data into a string for further manipulation. The actual size of the entity is part of the structure. So a couple definitions are used:

WORD textLen;
char fieldText[9999];

(You could define the size of the fieldText character array however you want - it would be even more efficient to dynamically allocate the right amount of memory at run-time).

The pointer to the entity is then read into to character array. The length of data comes from the wByteCount member of the MIME_PART structure:

textLen = pMime->wByteCount;
memcpy(fieldText, pText, textLen);
fieldText[textLen] = '\0';

After the data has been copied, the block needs to be unlocked:

OSUnlockBlock(fieldBlock);

And that's all there is to it. The fieldText character array now has the MIME entity data and can be further inspected.