Subject: elt and private.uid

From: brian moore <[email-masked]>
Date: Wed, 22 Jul 1998 11:17:58 -0700

Okay, I'm hacking around with c-client and found something I can't
figure out the intent of.

>From internal.txt, the elt item seems to be the place I want to grab
UID's from after a fetchstructure.  It's listed with the same precedence
as hours and answered and other useful things, and the intro paragraph says
"Applications may use the following".

But when I look at mail.h:

typedef struct message_cache {
   <snip>
  struct {                      /* c-client internal use only */
    unsigned long uid;          /* message unique ID */
    PARTTEXT special;           /* special text pointers */
    MESSAGE msg;                /* internal message pointers */
    unsigned int sequence : 1;  /* saved sequence bit; */
  } private;

Am I not supposed to snarf the UID out of the elt directly?  I know I
-could- call mail_uid, but it seems weird that I can get things like
recent flags and such straight from the elt and have to wrap reading the
uid.

Is reading from elt->private.uid a no-no as the 'private' name
implies, or am I being paranoid?

------------------------------------------------------------------
 For information about this mailing list, and its archives, see: 
 http://www.washington.edu/imap/c-client-list.html
------------------------------------------------------------------

---

From: Mark Crispin <[email-masked]>
Date: Wed, 22 Jul 1998 11:21:42 -0700 (PDT)

> recent flags and such straight from the elt and have to wrap reading the

Did you see the note about how you can't get flags and such from the elt
unless you first call fetchfast or fetchstructure?

> implies, or am I being paranoid?

Yes, reading from elt->private.uid is a no-no.  Don't do it.  The same applies
to the PARTTEXTs in BODY and MESSAGE.

>From the Gospel According to c-client:
	Learneth thou, so that thy wisdom shall be celebrated across the land:
	1) If c-client provides an access function, thou shalt *ALWAYS* use
	   the access function, so that thy application shall be reliable and
	   called wonderful.
	2) Look thou not upon those things labelled "private" in MESSAGECACHE,
	   nor spy upon PARTTEXTs in BODY and MESSAGE; for these are sacred
	   and posseseth great magic known only to c-client.  This magic is
	   unstable and reactive, and only through the oracle of the c-client
	   access functions may mortals achieve their goals unscathed.

---

From: brian moore <[email-masked]>
Date: Wed, 22 Jul 1998 11:55:16 -0700

> unless you first call fetchfast or fetchstructure?

Yep, a fetchstructure_full is right before that.

> to the PARTTEXTs in BODY and MESSAGE.

Hrrm... internal.txt should yank the reference then.  It does list uid
as something clients can snarf out of elt.  (Of course it's after
'FINAL' that I notice this, but that's the nature of documentation.)

It's the contradiction in the docs and the .h's that baffled me.

-- 
Brian Moore                             Kill A Spammer For Jesus
Sysadmin, C/Perl Hacker, Usenet Vandal

---

From: Mark Musone <[email-masked]>
Date: Wed, 22 Jul 1998 14:34:03 -0400 (EDT)

Well..

a few things,
according to the internal.txt file:
the MESSAGECACHE structure has
unsigned long uid; message unique id.

but i guess they changed the structure but didnt change the docs..

I wouldnt access the private part..
i looked in the pine sources...when in doubt my theory is see how pine does it :^)..
and they never access private.uid either. they call mail_uid.

so my non-professional opinion is to call mail_uid :^)
it shouldnt be a big deal, in fact i think it's a good thing to do.

actually i just looked at mail.c:

unsigned long mail_uid (MAILSTREAM *stream,unsigned long msgno)
{
  unsigned long uid = mail_elt (stream,msgno)->private.uid;
  return uid ? uid :
    (stream->dtb && stream->dtb->uid) ? (*stream->dtb->uid) (stream,msgno) : 0;
}

heh...but i still wouldn't access it directly..c-client does some wierd things..

			Mark

---

From: Mark Crispin <[email-masked]>
Date: Wed, 22 Jul 1998 12:04:56 -0700 (PDT)

> 'FINAL' that I notice this, but that's the nature of documentation.)

It does not describe elt->private.uid; it describes elt->uid which also no
longer exists.

If you'll notice, internal.txt was last revised on August 19, 1996, and
describes such functions as mail_lelt() which no longer exist.

Would you care to provide funding to get it updated?

---

From: Mark Musone <[email-masked]>
Date: Wed, 22 Jul 1998 14:47:28 -0400 (EDT)

I'd be happy to provide man-hours to get it updated.

			Mark

---

From: Mark Crispin <[email-masked]>
Date: Wed, 22 Jul 1998 12:16:05 -0700 (PDT)

> I'd be happy to provide man-hours to get it updated.

For the record, the "funding" comment was a joke.  That'll teach me to omit
smileys.  [*chagrined*]

As far as your volunteerism, why, thank you!!  It is much appreciated.  It
took a tremendous amount of work to update it the last time and I was not
looking forward to doing it again.

I suggest that you start with the current file (it's just a flat text file)
and mail.h.  Start with deleting the stuff that no longer exists (e.g.
mail_lelt()), and add in skeletons for the new stuff.  You'll probably need to
ask questions once you get into the new stuff, but there's a lot of plain old
editing that you should be able to do on your own.

There's probably a lot of clarifications that can be made in that document as
well.

Thanks again.  It'll help a lot.

---

From: brian moore <[email-masked]>
Date: Wed, 22 Jul 1998 16:50:59 -0700

> 	   the access function, so that thy application shall be reliable and

Okay, for the 'wish list' then, since this would, IMHO, be a Good Thing
for portability, a function to do the inverse of mail_uid would be
nice.

    for ( item = 1; item <= imap_stream->nmsgs; item++ )
	if (mail_uid(imap_stream,item) == uid) {
	    break;
	}

works, but it makes me sort of queasy with the caveat above.

(And I'd steal it from Pine, but Pine doesn't make much use of UID's and
I need them for disconnected operation.)

> 	   access functions may mortals achieve their goals unscathed.

So I shouldn't mention /etc/imapd.conf?

---

From: Mark Crispin <[email-masked]>
Date: Wed, 22 Jul 1998 17:25:28 -0700 (PDT)

> works, but it makes me sort of queasy with the caveat above.

Have I got a deal for you!!

mail_msgno()

It's not in internal.txt (I said it's 2 years old), but it's in c-client.