bluewave.htm

刚刚看到本站有Visual C++数字图象处理（人民邮电出版社）的电子书

before you include the bluewave.h file. this will define the data<br>
types as arrays of bytes, making it easier to create routines that<br>
will convert data fields between intel format and the format native to<br>
your cpu. (refer to &quot;byte ordering in file structures&quot; for more<br>
information.)<br>
<br>
several of the file structures -- the *.inf and *.upl headers --<br>
include fields that define the lengths of the other file structures<br>
used in mail and reply packet files. these fields are used to ensure<br>
that programs can use future releases of the file structures without<br>
breaking... as long as programs are coded to use them, that is.<br>
<br>
door authors should take the few extra lines of code to fill in the<br>
structure length fields. reader authors need to take the time to code<br>
for possible extensions to this file format. if the data fields are<br>
longer than expected, simply do a seek to move to the next record, and<br>
ignore the extra information. (if the data fields are shorter than<br>
expected, a simple &quot;please upgrade your reader&quot; should suffice.<br>
however, you should never encounter a record size smaller than the<br>
ones defined here.) any extra information that is sent in the packets<br>
probably would not be crucial, and you may be able to continue with<br>
reading the packet anyway.<br>
<br>
(it should be noted that all blue wave doors earlier than the version<br>
3.0 series set these fields to 0, as this extensibility was not added<br>
until recently. if the structure sizes are 0, readers should assume<br>
that all records are of the sizes defined in the header file as the<br>
&quot;original_xxxx_len&quot; macros, and should use these macros when field<br>
lengths of 0 are encountered. there is no definition for the original<br>
length of the *.upl structures, as the older doors did not recognize<br>
the *.upl file.)<br>
<br>
to see an example of how to use these structure length fields, refer<br>
to the comments in the bluewave.h file. there, you will see a c code<br>
snippet that not only demonstrates the length fields, but the<br>
original_xxxx_len macros as well.<br>
<br>
important note: all blue wave file structures must be stored in<br>
&quot;packed&quot; format (i.e. the compiler must not insert padding between<br>
fields in order to force fields onto word boundaries). most compilers<br>
default to &quot;packed&quot; mode, but if yours does not, you must use the<br>
appropriate settings or preprocessor directives to set &quot;packed&quot; mode.<br>
failure to do so will all but guarantee that your program will gener-<br>
ate incompatible blue wave packets!<br>
<br>
<br>
<a name="unused and reserved structure fields">unused and reserved structure fields</a><br>
====================================<br>
<br>
some fields and flags in the blue wave structures are either not<br>
defined, or are marked as being reserved for future use. these areas<br>
are not to be used by programmers, unless otherwise indicated. they<br>
are reserved for future expansion and enhancement of the blue wave<br>
packet structures, and if you use them for your own purposes, you run<br>
the risk of making your program incompatible with future updates of<br>
the file structures.<br>
<br>
furthermore, future structure updates will assume that these unused<br>
areas are &quot;garbage-free&quot; (i.e. they are filled with 0 values). in<br>
order to cover all bases, then, all unused areas should be set to 0.<br>
this can be easily done with the standard c function memset(). for<br>
example, using:<br>
<br>
memset(&amp;infhdr, 0, sizeof(inf_header));<br>
<br>
before you begin adding information to the *.inf header structure will<br>
ensure that all unused fields are set to 0. this should be done<br>
before adding information to *any* blue wave file structure.<br>
<br>
<br>
<a name="the *.inf file (inf_header &amp; inf_area_info)">the *.inf file (inf_header &amp;
inf_area_info)</a><br>
===========================================<br>
<br>
the *.inf file consists of two &quot;parts&quot;: a header, which contains<br>
information about the host system and the user to whom the packet is<br>
intended, and a series of records that contain the information on all<br>
message bases available on the host system. (the latter is used in a<br>
reader both for posting replies and offline configuration.) the<br>
header structure is known as inf_header, and the record structure is<br>
known as inf_area_info.<br>
<br>
most of the fields in inf_header are self-explanatory. the following<br>
fields, however, deserve extra attention:<br>
<br>
ver packet version level. this is a crucial<br>
field, as it allows doors and readers to<br>
determine the revision level of the file<br>
structures used to create the packet. pro-<br>
grams should check this field to insure that<br>
they can properly handle the packet; doors<br>
should store in this field the current packet<br>
revision level, shown at the top of this<br>
document.<br>
<br>
readerfiles files that can be displayed by the reader.<br>
these are usually bulletins, sign-on banners,<br>
etc. up to five files can be specified.<br>
<br>
keywords specifies the keywords used while bundling<br>
messages. door authors that wish to provide<br>
keyword support should refer to the blue wave<br>
user documentation for more information.<br>
<br>
filters same as above, but specifies the filters used<br>
while bundling messages.<br>
<br>
macros same as above, but specifies the macros used<br>
in the door to specify message bundling<br>
operations.<br>
<br>
can_forward indicates that the user can forward messages<br>
to other message areas from within a reader.<br>
<br>
inf_header_len length of inf_header used in mail packet.<br>
door authors are required to fill this field;<br>
reader authors should use this field to<br>
properly parse the *.inf file. the current<br>
crop of blue wave doors properly fill this<br>
field, but older versions may not. refer to<br>
the header file for more information on using<br>
this field.<br>
<br>
inf_areainfo_len same as above, but specifies the length of<br>
the inf_area_info structure.<br>
<br>
mix_structlen same as above, but specifies the length of<br>
the *.mix file structure (mix_rec).<br>
<br>
fti_structlen same as above, but specifies the length of<br>
the *.fti file structure (fti_rec).<br>
<br>
uses_upl_file a non-zero value in this field indicates that<br>
the door which create the mail packet can<br>
process reply packets stored in the *.upl<br>
format. if zero, the door can only handle<br>
reply packets stored in the older *.upi and<br>
*.net formats. (these formats are discussed<br>
later.)<br>
<br>
packet_id the packet id used by the host system, which<br>
can be used by readers to properly access<br>
mail packet control files even if the mail<br>
packet itself has been renamed. (if this<br>
field is not filled, readers should assume<br>
that the root name of the mail packet is the<br>
packet id.)<br>
<br>
the inf_area_info structure fields are defined as follows:<br>
<br>
areanum the area number on the host system for which<br>
the record defines, specified as an ascii<br>
string. this field will correspond to the<br>
similar field in the *.mix structure (dis-<br>
cussed later). this does not necessarily<br>
have to be a number, so a case-insensitive<br>
match should be performed when doing any<br>
comparisons using this field.<br>
<br>
echotag the area tag name for which the record de-<br>
fines. this field is used in the reply<br>
packet to link reply messages to the destina-<br>
tion areas on the host system, and must be<br>
unique (i.e. there cannot be two or more<br>
identical area tags).<br>
<br>
title the message area description.<br>
<br>
area_flags specifies the unique characteristics of the<br>
message area for which the record defines.<br>
most of the flags are self-explanatory, as<br>
specified in the header file; the network<br>
area flags, however, need to be clarified.<br>
if the message area is part of a network<br>
(i.e. fidonet), the inf_echo flag should be<br>
set; this will allow a reader to properly<br>
handle network mail. if the area is for<br>
private network mail, the inf_netmail flag<br>
should also be set.<br>
<br>
network_type specifies the network type for which the<br>
defined message area belongs. note that the<br>
network type is specified as a full byte<br>
value, not as a bit flag. (if the inf_echo<br>
flag is not set, the network type can be<br>
ignored, obviously.)<br>
<br>
<br>
<a name="the *.mix file (mix_rec)">the *.mix file (mix_rec)</a><br>
========================<br>
<br>
each record in the *.mix file points to the beginning of the area in<br>
the *.fti file that contains the header information for messages that<br>
were obtained from each message area. note that *only* the areas for<br>
which messages were extracted will have a corresponding *.mix record.<br>
<br>
each structure field is defined as follows:<br>
<br>
areanum corresponds to the identical field in the<br>
*.inf record for the particular message area.<br>
it is used by the reader to coordinate the<br>
information between the *.inf and *.mix<br>
records. again, case-insensitive comparisons<br>
should be performed when using this field, as<br>
this field does not have to contain a numeri-<br>
cal value.<br>
<br>
totmsgs total number of messages in this area. up to<br>
65,535 messages per area are allowed (the<br>
limit of an unsigned 16-bit integer).<br>
<br>
numpers total number of messages in this area that<br>
are directed specifically to the user who<br>
bundled the mail packet. this value is<br>
usually obtained during message bundling by<br>
comparing the name in the &quot;to:&quot; field to the<br>
user name for every message, and incrementing<br>
a counter if they match. (reader authors can<br>
feel free to disregard this value and perform<br>
their own search for personal messages, once<br>
the packet is loaded into the program.)<br>
<br>
msghptr pointer to the first record in the *.fti file<br>
that corresponds to this message area. note<br>
that this specifies the byte offset into the<br>
*.fti file, *not* the record number; thus,<br>
programmers can use the seek() or lseek()<br>
functions to quickly point to the proper<br>
section of the *.fti file.<br>
<br>
<br>
<a name="the *.fti file (fti_rec)">the *.fti file (fti_rec)</a><br>
========================<br>
<br>
the *.fti record specifies the header information for messages in the<br>
mail packet, along with additional information such as the length of<br>
the message and the pointer to the message stored in the *.dat file.<br>
these records are stored sequentially in the *.fti file, with all the<br>
headers for the first message area stored first, followed by the<br>
headers for the second message area, and so forth.<br>
<br>
most of the fields are self-explanatory, with the following fields<br>
described in more detail:<br>
<br>
msgnum the message number as stored on the host<br>
system. this provides an &quot;absolute&quot; message<br>
number for use with message threading.<br>
<br>
replyto indicates the absolute message number for<br>
which this message is a reply (the &quot;previous&quot;<br>
message). if zero, there is no previous<br>
message.<br>
<br>
replyat indicates the absolute message number of a<br>
reply to this message (the &quot;next&quot; message).<br>
if zero, there is no next message.<br>
<br>
msgptr pointer to the start of the message text in<br>
the *.dat file. this is a byte offset, thus<br>
a programmer can use the seek() or lseek()<br>
functions to quickly point to the proper<br>
position in the *.dat file.<br>
<br>
msglength length of the message text (in bytes) plus 1.<br>
the addition of 1 is done to compensate for<br>
the required space character in front of the<br>
message text (described below).<br>
<br>
flags bit-mapped message status flags. note that<br>
for fidonet network messages, these flags are<br>
*not* stored in the exact same order as<br>
specified in the fidonet technical standards,<br>
even though they are identical in function.<br>
<p><a name="the *.dat file">the *.dat file</a><br>
==============<br>
<br>
the *.dat file contains the text of all messages obtained from the<br>
host system. valid messages begin with an ascii space character (&quot; &quot;,<br>
decimal 32, hexadecimal 20), followed by the message text itself.<br>
note that the space character is *not* to be considered a part of the<br>
message text; it is simply a marker used to indicate the start of a<br>
valid block of text, and *must* be present for each message specified<br>
in the *.fti file (even if there is no message text at all). the<br>
messages in the *.dat file should be in the same order as specified in<br>
the *.fti file, though this is not a requirement (due to the fact that<br>
the *.dat file is unstructured).<br>
<br>
<br>
<a name="the *.xti file (xti_rec)">the *.xti file (xti_rec)</a><br>
========================<br>
<br>
each record in the *.xti file corresponds to a record in the *.fti<br>
file, and specifies extended status information for each message (the<br>
&quot;save&quot;, &quot;reply&quot;, &quot;print&quot;, and &quot;delete&quot; flags used
by the blue wave<br>
reader). note that this file is *not* created by any blue wave door;<br>
it is created on-the-fly by the blue wave reader. (the fields and<br>
flags used in xti_rec are self-explanatory, thus they will not be<br>
explained here.)<br>
<br>
note: the *.xti file is not an official part of the blue wave<br>
specification. it is documented here solely for the benefit<br>
of third-party authors who might wish to create a similar<br>
file for their own applications. if so, authors should not<br>
use the &quot;xti&quot; extension on their own files if they differ<br>
from the xti_rec format, as this extension is used on the<br>
file created by the blue wave offline mail reader (which<br>
expects the file to use the xti_rec format). on the other<br>
hand, authors can use the &quot;xti&quot; extension as long as the<br>
xti_rec format is used.<br>
<br>
<br>
<a name="the *.upl file (upl_header &amp; upl_rec)">the *.upl file (upl_header &amp;