Daniel Nashed's Blog

C-API - NSFItemGetText() returns multiple entries in a single text string

I learned something new today. After working with the Notes C-API for half of my life, I found out about how NSFItemGetText() handles text lists -- OMG

My impression was always it would just get the first entry..
But no ---  It does implode the whole test list for you and creates a single string with the elements separated by "; ".

So for example when your application reads host entries from the HTTP tab the result could look like this:

Domino FQDN : [pluto.csi-domino.com; two.csi-domino.com]

This can be a very wanted display behavior. But in other cases you might only want the first entry.
In my case this broke the application logic and the resulting string wasn't a proper IDN string which caused a failure in init for a cache -- which wasn't what was intended at all ...

So if you want to make sure you are always getting just one entry independent of the field type (TEXT or TEXT_LIST) you can use NSFItemGetTextListEntry().

But you have to take care about important differences between the functions.
NSFItemGetTextListEntry will get the first entry if you use the index 0. And it will work on TEXT and TEXT_LIST.
In contrast to NSFItemGetText  the string is NOT null terminated and you need to keep room for an additional null terminator byte if you care for null terminated strings.

Now with that difference in mind, you see how important it is to use the fields in the Domino directory carefully.
For example the InternetAddress in the person document is a TEXT field and it isn't guaranteed that everyone who reads it, will always use a function that can handle a TEXT_LIST properly.

So you could run into some unexpected results with existing applications today. Or applications in future.

For me the behavior of NSFItemGetText wasn't expected at all. The C-API reference guide does not documented this behavior.
And it is really strange, I never ran into it in my whole C-API developer life.

No this isn't new behavior! I just never ran into it and had to find out today..

-- Daniel



Reference information:


WORD LNPUBLIC NSFItemGetText(
       NOTEHANDLE  note_handle,
       const char far *item_name,
       char far *item_text,
       WORD  text_len);


WORD LNPUBLIC NSFItemGetTextListEntry(
       NOTEHANDLE  note_handle,
       const char far *item_name,
       WORD  entry_position,
       char far *entry_text,
       WORD  text_len);

-----


Field Name: InternetAddress
Data Type: Text
Data Length: 24 bytes
Seq Num: 1
Dup Item ID: 0
Field Flags: SUMMARY PROTECTED

• Comments [0]