/
smapi.pas
1048 lines (845 loc) · 43.2 KB
/
smapi.pas
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
{: Pascal (Delphi/ Kylix) Interface unit for the smapi. Documentation comments
are taken from sqdev.prn, which is part of Scott Dudley's SQDEV200.zip archive. }
{: NOTE: Unfortunately it turned out that the structures that are passed
between smapi and any calling programs are in no way align controlled,
that is, how they are aligned is left to the compiler.
That means that if you are not using the same compiler for your
program that was used to compile the libraries, chances are that
you will have an alignment problem resulting in fields of the
structures being out of sync, e.g. you are reading something totally
different from what the library put there.
Because of this and because I don't want to chase a moving target
like this, I will stop maintaining smapi.pas and fidoconf.pas.
That probably means that husky has now become a project that can
only be used by C programmers, unless somebody else wants
to go through the trouble.
One possible solution I can think of, would be having an interface
layer that converts the randomly aligned structures to other
structures that are fixed. I might do it, maybe, if I don't find
anything else to waste my time on. But this is rather unlikely,
because it has to be done in C and that is definitely not my
favourite programming language.
Please leave this comment in here, so nobody else will waste time
trying to figure out why the data his programs reads is wrong.
2001-07-22 twm }
unit smapi;
interface
type
// this assumes that a word is 2 bytes and a longword is 4 bytes, true
// for Delphi 5 and Kylix.
sword = word;
dword = longword;
PPChar = ^PChar;
PLongint = ^Longint;
const
MSGAREA_NORMAL = $00; // read/write
MSGAREA_CREATE = $01; // create
MSGAREA_CRIFNEC = $02; // create if necessary
MSGTYPE_SDM = $01; // *.MSG
MSGTYPE_SQUISH = $02; // squish
MSGTYPE_JAM = $08; // jam
MSGTYPE_ECHO = $80;
MSGTYPE_NOTH = $0100; // ??
MSGNUM_CUR: longint = -1;
MSGNUM_PREV: longint = -2;
MSGNUM_NEXT: longint = -3;
MSGNUM_current: longint = -1;
MSGNUM_previous: longint = -2;
MOPEN_CREATE = 0;
MOPEN_READ = 1;
MOPEN_WRITE = 2;
MOPEN_RW = 3;
MSGAPI_VERSION = 1;
SMAPI_VERSION = '1.5.65.65.65.65.6';
MSGPRIVATE = $00001;
MSGCRASH = $00002;
MSGREAD = $00004;
MSGSENT = $00008;
MSGFILE = $00010;
MSGFWD = $00020; // also called intransit flag
MSGORPHAN = $00040;
MSGKILL = $00080;
MSGLOCAL = $00100;
MSGHOLD = $00200;
MSGXX2 = $00400;
MSGFRQ = $00800;
MSGRRQ = $01000;
MSGCPT = $02000;
MSGARQ = $04000;
MSGURQ = $08000;
MSGSCANNED = $10000;
MSGLOCKED: dword = $40000000; // seems to be a feature of GoldEd
XMSG_NAME_SIZE = 36;
XMSG_FROM_SIZE = XMSG_NAME_SIZE;
XMSG_TO_SIZE = XMSG_NAME_SIZE;
XMSG_SUBJ_SIZE = 72;
MAX_REPLY = 9;
FTS0001_DATE_SIZE = 20;
XMSG_SIZE = ((94 + XMSG_FROM_SIZE) + XMSG_TO_SIZE) + XMSG_SUBJ_SIZE;
MSGAPI_ID: dword = $0201414D;
MSGH_ID = $0302484D;
UID_EXACT = $00;
UID_NEXT = $01;
UID_PREV = $02;
// error constants
MERR_NONE = 0; // No error
MERR_BADH = 1; // Invalid handle passed to function
MERR_BADF = 2; // Invalid or corrupted file
MERR_NOMEM = 3; // Not enough memory for specified operation
MERR_NODS = 4; // Maybe not enough disk space for operation
MERR_NOENT = 5; // File/message does not exist
MERR_BADA = 6; // Bad argument passed to msgapi function
MERR_EOPEN = 7; // Couldn't close - messages still open
BROWSE_ACUR = $0001;
BROWSE_ATAG = $0002;
BROWSE_AALL = $0004;
BROWSE_ALL = $0008;
BROWSE_NEW = $0010;
BROWSE_SEARCH = $0020;
BROWSE_FROM = $0040;
BROWSE_READ = $0100;
BROWSE_LIST = $0200;
BROWSE_QWK = $0400;
BROWSE_GETTXT = $0800;
BROWSE_EXACT = $1000;
BROWSE_HASH = $2000;
BROWSE_AREA = (BROWSE_ACUR or BROWSE_ATAG) or BROWSE_AALL;
BROWSE_TYPE = ((BROWSE_ALL or BROWSE_NEW) or BROWSE_SEARCH) or BROWSE_FROM;
BROWSE_DISPLAY = (BROWSE_READ or BROWSE_LIST) or BROWSE_QWK;
SF_HAS_ATTR = $01;
SF_NOT_ATTR = $02;
SF_OR = $04;
SF_AND = $08;
WHERE_TO = $01;
WHERE_FROM = $02;
WHERE_SUBJ = $04;
WHERE_BODY = $08;
WHERE_ALL = ((WHERE_TO or WHERE_FROM) or WHERE_SUBJ) or WHERE_BODY;
SCAN_BLOCK_SDM = 48;
SCAN_BLOCK_SQUISH = 512;
type
PAreaHandle = ^TAreaHandle;
PMsgHandle = ^TMsgHandle;
PXMSG = ^TXMSG;
PNETADDR = ^TNETADDR;
PSEARCH = ^TSEARCH;
PBROWSE = ^TBROWSE;
TUMsgId = dword;
{ Timestamp }
TStamp = packed record
// This was true for the original Squish MsgAPI, but smapi is double word aligned
// case Boolean of
// True: (Date, Time: sword);
// False: (Value: dword);
Date, Time: sword;
end;
PMINF = ^TMINF;
TMINF = packed record
req_version: sword;
def_zone: sword;
haveshare: sword;
// necessary for Versions >= 1 always set to NIL
palloc: pointer;
pfree: pointer;
repalloc: pointer;
farpalloc: pointer;
farpfree: pointer;
farrepalloc: pointer;
end;
TNetAddr = packed record
zone: sword;
net: sword;
node: sword;
point: sword;
end;
TMsgName = packed array[0..XMSG_NAME_SIZE - 1] of char;
TMsgSubj = packed array[0..XMSG_SUBJ_SIZE - 1] of Char;
// TMsgSubjStr = string[XMSG_SUBJ_SIZE];
TXMSG = packed record
attr: dword;
from: TMsgName;
_to: TMsgName;
subj: TMsgSubj;
orig: TNetAddr;
dest: TNetAddr;
date_written: TStamp;
date_arrived: TStamp;
utc_ofs: sword;
replyto: TUMsgId;
Replies: array[0..MAX_REPLY - 1] of TUMsgId;
filler2: dword; // dword align
FtscData: array[0..FTS0001_DATE_SIZE - 1] of Char;
end;
TApiFuncs = packed record
CloseArea: function(mh: PAreaHandle): sword; cdecl;
OpenMsg: function(mh: PAreaHandle; mode: sword; n: dword): PMsgHandle; cdecl;
CloseMsg: function(msgh: PMsgHandle): sword; cdecl;
ReadMsg: function(msgh: PMsgHandle; msg: PXMSG; ofs: dword; bytes: dword; text: PChar; cbyt: dword; ctxt: PChar): dword; cdecl;
WriteMsg: function(msgh: PMsgHandle; append: sword; msg: PXMSG; text: PChar; textlen: dword; totlen: dword; clen: dword; ctxt: PChar): sword; cdecl;
KillMsg: function(mh: PAreaHandle; msgnum: dword): sword; cdecl;
Lock: function(mh: PAreaHandle): sword; cdecl;
UnLock: function(mh: PAreaHandle): sword; cdecl;
SetCurPos: function(msgh: PMsgHandle; pos: dword): sword; cdecl;
GetCurPos: function(msgh: PMsgHandle): dword; cdecl;
MsgnToUid: function(mh: PAreaHandle; msgnum: dword): TUMsgId; cdecl;
UidToMsgn: function(mh: PAreaHandle; UMsgId: TUMsgId; _type: sword): dword; cdecl;
GetHighWater: function(mh: PAreaHandle): dword; cdecl;
SetHighWater: function(mh: PAreaHandle; hwm: dword): sword; cdecl;
GetTextLen: function(msgh: PMsgHandle): dword; cdecl;
GetCtrlLen: function(msgh: PMsgHandle): dword; cdecl;
end;
PApiFuncs = ^TApiFuncs;
TMSGAPI = packed record
id: dword;
len: sword;
_type: sword;
num_msg: dword;
cur_msg: dword;
high_msg: dword;
high_water: dword;
sz_xmsg: sword;
locked: byte;
isecho: byte;
api: PApiFuncs;
apidata: pointer; // Pointer to application-specific data.
// API_SQ.C and API_SDM.C use this for
// different things, so again, no applications
// should muck with anything in here.
end;
TAreaHandle = TMSGAPI;
TMsgHandle = packed record
sq: PAreaHandle;
id: dword;
bytes_written: dword;
cur_pos: dword;
end;
TSEARCH = packed record
next: PSEARCH;
attr: longint;
flag: longint;
txt: Pchar;
where: char;
end;
TBROWSE = packed record
path: Pchar;
_type: sword;
bflag: sword;
bdata: dword;
first: PSEARCH;
nonstop: Pchar;
msgn: dword;
sq: PAreaHandle;
m: PMsgHandle;
msg: TXMSG;
matched: sword;
Begin_Ptr: function(b: pBROWSE): longint; cdecl;
Status_Ptr: function(b: pBROWSE; aname: pchar; colour: longint): longint;
Idle_Ptr: function(b: pBROWSE): longint;
Display_Ptr: function(b: pBROWSE): longint;
After_Ptr: function(b: pBROWSE): longint;
End_Ptr: function(b: pBROWSE): longint;
Match_Ptr: function(b: pBROWSE): longint;
end;
//Var
// msgapierr: sword; cvar; external;
// mi: minf; cvar; external;
{: Helper function. Since Delphi/Kylix does not support external variables,
this function has been introduced. It reads the smapi error variable
msgapierr and returns its value }
function MsgGetMsgApiErr: sword; cdecl;
{: Closes a message area.
This function performs all clean-up actions necessary, such as closing files,
changing directories, and so on. The MsgCloseArea function should be
called for each area opened by MsgOpenArea.
@param AreaHandle is an HAREA handle returnded by MsgOpenArea.
@returns 0 if the area was successfully closed, otherwise it returns -1
and msgapierr is set to one of the following:
MERR_BADH An invalid handle was passed to the function.
MERR_EOPEN Messages are still open in this area, so the area
could not be closed. }
function MsgCloseArea(_AreaHandle: PAreaHandle): sword; cdecl;
{: Opens a message for access, and it must be used to read from or write to
a given message.
@param AreaHandle is a message area handle, as returned by the MsgOpenArea
function.
@param Mode is an access flag, containing one of the following manifest
constants:
MOPEN_CREATE Create a new message. This mode should only
be used for creating new messages.
MOPEN_READ Open an existing message for reading ONLY.
MOPEN_WRITE Open an existing message for writing ONLY.
MOPEN_RW Open an existing message for reading AND writing.
@param MsgNum is the specified message number to open. If mode is either
MOPEN_READ, MOPEN_WRITE or MOPEN_RW, the message number must
currently exist in the specified area. If mode is set to
MOPEN_CREATE, a value of 0 for 'msgn' indicates that a new
message should be created, and assigned a number one higher
than the current highest message. If MsgN is non-zero, but
MOPEN_CREATE is set to the number of a currently-existing
message, the specified message will be truncated and the
new message will take its place.
For MOPEN_READ or MOPEN_RW, the following constants can also
be passed in place of 'msgn':
MSGNUM_CUR Open the last message which was accessed by MsgOpenMsg.
MSGNUM_PREV Open the message prior to the last message accessed
by MsgOpenMsg.
MSGNUM_NEXT Open the message after the last message accessed by
MsgOpenMsg.
The MsgAPI maintains the number of the last message opened by
MsgOpenMsg, which is used when processing these constants.
(See also MsgGetCurMsg.)
@returns a HMSG handle ff the message was successfully opened. Otherwise,
a value of NULL is returned, and msgapierr will be set to one of
the following:
MERR_NOENT
MERR_NOMEM
MERR_BADF
MERR_BADA
MERR_BADH }
function MsgOpenMsg(_AreaHandle: PAreaHandle; _Mode: sword; _MsgNum: dword): PMsgHandle; cdecl;
{: Closes a message which has been previously opened by MsgOpenMsg.
All messages should be closed after use, or else data loss may result.
@params MsgHandle is the message handle that was returned by MsgOpenMsg.
@returns 0, if the message was successfully closed, otherwise, -1 is
returned, and msgapierr is set to:
MERR_BADH }
function MsgCloseMsg(_MsgHandle: PMsgHandle): sword; cdecl;
{: Reads a message from disk.
This function can be used to read all parts of a message, including the
message header, message body, and control information.
@param MsgHandle is a message handle, as returned by the MsgOpenMsg function.
The message in question must have been opened with a mode of either
MOPEN_READ or MOPEN_RW.
@param XMsg is a pointer to an TXMSG (extended message) structure.
The format of this structure is detailed in the Squish File Format
Specification section, but it contains all of the message information
that is found in the message header, including the to/from/subject
fields, origination and arrival dates, 4D origination and destination
addresses, and so forth. (See the appendices for specific information
on the XMSG structure itself.)
If the application wishes to read the header of a given message, this
argument should point to an XMSG structure. Otherwise, this argument
should be NULL, which informs the API that the message header does
not need to be read.
@param Offset is used for reading message text in a multiple-pass environment.
This defines the offset in the message body from which the API should
start reading. To start reading from the beginning of the message,
a value of 0L should be given. Otherwise, the offset into the message
(in bytes) should be given for this argument. If the application does
not wish to read the message body, this argument should be set to 0L.
@param BodyLen represents the maximum number of bytes to read from the message.
Fewer bytes may be read, but the API will read no more than BodyLen
during this call. (See BodyLen, and also this function's return value.)
If the application does not wish to read the message body, this
argument should be set to 0L.
@param Body is a pointer to a block of memory, into which the API will place
the message body. The message body will be read from the position
specified by Offset, up to a maximum of BodyLen bytes. If the
application does not wish to read the message body, this argument
should be set to NULL.
@param ControlLen represents the maximum number of bytes of control
information to read from the message.
@param Control is a pointer to a block of memory, into which the API will
place the message control information. No more than ControlLne bytes
of control information will be placed into the buffer.
NOTE: unlike the message text functions, control information can only
be read in one pass.
The text read by this function is free-form. The message body may or may not
contain control characters, NULs, or any other sequence of characters.
Messages are simply treated as a block of bytes, with no interpretation
whatsoever.
In FidoNet areas, the message body consists of one or more paragraphs of
text. Each paragraph is delimited by a hard carriage return, '\r', or
ASCII 13. Each paragraph can be of any length, so the text should be
wordwrapped onto logical lines before being displayed. If created by older
applications, paragraphs may also contain linefeeds ('\n') and soft returns
('\x8d') at the end of each line, but these are optional and should always be
ignored.
As an example, assume that the following stream of text was returned by
MsgReadMsg():
"Hi!\r\rHow's it going? I got the new MsgAPI kit today!\r\rAnyhow, gotta run!"
The "\r" marks are carriage returns, so they indicate the end of a paragraph.
Notice that the second paragraph is fairly long, so it might have to be
wordwrapped, depending on the screen width. Your application might wordwrap
the text to make it look like this, if using a window 40 characters wide:
-----------------------------------------
| Hi! |
| |
| How's it going? I got the new MsgAPI |
| kit today! |
| |
| Anyhow, gotta run! |
-----------------------------------------
Paragraphs should always be wordwrapped by the application, regardless
of the screen/window size. When parsing the message text, linefeeds and
soft carriage returns should be simply skipped.
The 'message control information' has a somewhat more restricted format.
The control information is passed to the application in the form of an
ASCIIZ string. The control information is a variable-length string of text
which contains information not found in the (fixed-size) message header.
The format of control information is given by the following regular
expression:
(group)+<NUL>
A 'group' consists of a <SOH> and a control item.
<SOH> is the Start Of Header character, or ASCII 01. All control information
strings must begin with an SOH, whether or not control items are present.
Following the <SOH> is a control item. A control item consists of a string
which describes the type of control item, or it may consist of nothing.
At least one group must be present in each message. If a message has no extra
control information, this field should consists of a <SOH> followed by a
single <NUL>.
Although the control items are free-form, the following format is
suggested:
<SOH>tag: value
where 'tag' is a descriptive identifier, describing the type of field that
the item represents. 'value' is simply free-form text, which continues up
until the next SOH or <NUL>.
The character set for the tag and value consists of those characters in the
range 2-255, inclusive.
As an example, a message might have the following control information:
<SOH>CHARSET: LATIN1<SOH>REALNAME: Mark Twain<NUL>
The trailing <NUL> byte must be included in the read count given by 'cbyt'.
@returns the number of bytes read from the message body. If no characters
were requested, this function returns 0.
On error, the function returns -1 and sets msgapierr to one
of the following:
MERR_BADH
MERR_BADF
MERR_NOMEM }
function MsgReadMsg(_MsgHandle: PMsgHandle; _XMsg: PXMSG; _Offset: dword;
_BodyLen: dword; _Body: PChar; _ControlLen: dword; _Control: PChar): integer; cdecl;
{: Writes the message header, body, and control information to a message.
@param MsgHandle is a message handle, as returned by the MsgOpenMsg
function. The message must have been opened with a mode of
MOPEN_CREATE, MOPEN_WRITE or MOPEN_RW.
@param Append is a boolean flag, indicating the state of the message body.
If Append is zero, then the API will write the message body starting
at offset zero. Otherwise, if Append is non-zero, the API will
continue writing from the offset used by the last MsgWriteMsg call.
This flag applies to the message body only; if no text is to be
written to the body, this argument should be set to 0.
@param XMsg is a pointer to an XMSG structure. If this pointer is non-NULL,
then MsgWriteMsg will place the XMSG structure information into the
message's physical header. To leave the header unmodified, NULL should
be passed for XMsg.
THIS PARAMETER MUST BE PASSED THE **FIRST** TIME THAT MSGWRITEMSG()
IS USED WITH A JUST-OPENED MESSAGE HANDLE!
@param Body points to an array of bytes to be written to the message body.
If no text is to be written, this argument should be NULL.
@param Bodylen indicates the number of bytes to be written to the message
body in this pass of the MsgWriteMsg function. The text is free-format,
and it can consist of any characters, including NULs and control
characters. If the application does not wish to update the message
body, a value of 0L should be passed for this argument.
@param Total indicates the total length of the message to be written. This
differs from Bodylen in that the message may be written a piece at a
time (using small Bodylen values), but the total length of the message
will not exceed Total. This parameter can be somewhat restrictive for
the application; however, this value is required for optimal use of
some message base types. The Total value does not have to be the exact
length of the message to write; however, space may be wasted if this
value is not reasonably close to the actual length of the message.
The rationale behind this argument is that it gives the API writer
the most flexibility, in terms of supporting future message base
formats. If the application can provide this information to the API,
then almost any message base format can be supported by simply dropping
in a new API module or DLL.
To write text by making multiple passes, the FIRST pass should call
MsgWriteMsg with Append set to 0, with the total length of the message
in Total, and the length of Body in Bodylen. Second and subsequent
passes should set Append to 1, with the length of Body in Bodylen.
If the application does not wish to update the message body of an
existing message, a value of 0L should be passed for this argument.
This argument MUST be specified during the first call to the
MsgWriteMsg when using a mode of MOPEN_CREATE, even if the first
call is not requesting any text to be written.
However, this value will be stored internally, and ignored on the
second and later calls.
When operating on a preexisting message (opened with MOPEN_WRITE or
MOPEN_RW), it is an error to specify a length in 'totlen' which is
greater than the original length of the message.
@param ControlLen specifies the total length of the control information,
including the trailing NUL byte. To write no control information,
a value of 0L should be passed for this argument.
@param Control is a pointer to the control information string. To write no
control information, a value of 0L should be passed for this argument.
N.B. Several restrictions apply to writing control information:
First and foremost, control information can only be written once.
If the control information is to be changed, the message must be read
and copied to another message.
Secondly, control information MUST be written during or before
MsgWriteMsg is called with information about the message body.
@returns a value of 0 on success, or -1 on error. If an error occurred,
msgapierr will be set to one of the following values:
MERR_BADH
MERR_BADF
MERR_NOMEM
MERR_NODS }
function MsgWriteMsg(_MsgHandle: PMsgHandle; _Append: sword; _XMsg: PXMSG;
_Body: PChar; _Bodylen: dword; _Total: dword; _ControlLen: dword;
_Control: PChar): sword; cdecl;
{: Deletes a message from the specified message area.
@param AreaHandle is a message area handle, as returned by MsgOpenArea.
@param MsgNum specifies the message number to kill.
It is an error to kill a message which is currently open.
@returns a value of 0 if the message was successfully killed, or it
returns -1 on error and sets msgapierr to one of the following:
MERR_BADH
MERR_NOENT
MERR_BADF
MERR_NOMEM }
function MsgKillMsg(_AreaHandle: PAreaHandle; _MsgNum: dword): sword; cdecl;
function MsgLock(mh: PAreaHandle): sword; cdecl;
function MsgUnLock(mh: PAreaHandle): sword; cdecl;
{: Sets the 'current position' in a message handle. This position is used by
MsgReadMsg to read text from the message body.
@param MsgHandle is a message handle, as returned by MsgOpenMsg.
@param Pos is the number of bytes into the message from which MsgReadMsg
should start reading.
@returns 0 on success, or -1 on error and sets msgapierr to:
MERR_BADH }
function MsgSetCurPos(_MsgHandle: PMsgHandle; _Pos: dword): sword; cdecl;
{: Retrieves the 'current position' of a message handle. This position is
where the MsgReadMsg would read text from the message body next.
@param MsgHandle is a message handle, as returned by MsgOpenMsg.
MsgGetCurPos returns the offset into the message on success, or (dword)-1 on
error and sets msgapierr to:
MERR_BADH }
function MsgGetCurPos(_MsgHandle: PMsgHandle): dword; cdecl;
{: Converts a message number to a 'unique message ID', or UMSGID. This function
can be used to maintain pointers to an 'absolute' message number, regardless
of whether or not the area is renumbered or packed. The MsgMsgnToUid
function converts a message number to a UMSGID, and the MsgUidToMsgn
function converts that UMSGID back to a message number.
@param AreaHandle is the message area handle, as returned by MsgOpenArea.
@param MsgNum is the message number to convert.
@returns a UMSGID on success; otherwise, it returns 0 and sets msgapierr to:
MERR_BADH
MERR_BADF
MERR_NOENT }
function MsgMsgnToUid(_AreaHandle: PAreaHandle; _MsgNum: dword): TUMsgId; cdecl;
{: Converts a UMSGID to a message number.
@param AreaHandle is the message area handle, as returned by MsgOpenArea.
@param UMsgId is the UMSGID, as returned by a prior call to MsgMsgnToUid.
@param Type is the type of conversion to perform. Type can be any of the
following values:
UID_EXACT Return the message number represented by the UMSGID,
or 0 if the message no longer exists.
UID_PREV Return the message number represented by the UMSGID.
If the message no longer exists, the number of the
preceding message will be returned.
UID_NEXT Return the message number represented by the UMSGID.
If the message no longer exists, the number of the
following message will be returned.
@returns the requested UMSGID. If no valid message could be found,
MsgUidToMsgn returns 0 and sets msgapierr to one of the
following:
MERR_BADH
MERR_NOENT }
function MsgUidToMsgn(_AreaHandle: PAreaHandle; _UMsgId: TUMsgId; _Type: sword): dword; cdecl;
{: Returns the 'high water marker' for an area.
This number represents the highest message number that was processed by a
message export or import utility. The high water marker is automatically
adjusted when messages are killed.
@param AreaHandle is a message area handle, as returned by MsgOpenArea.
@returns the high water mark on success, or 0 on error and
sets msgapierr to: MERR_BADH }
function MsgGetHighWater(_AreaHandle: PAreaHandle): dword; cdecl;
{: Sets the 'high water marker' for the current area.
@param AreaHandle is a message area handle, as returned by MsgOpenArea.
@param HighWater is the new high water marker to use for the specified area.
@returns 0 on success, or -1 on error and sets msgapierr to:
MERR_BADH }
function MsgSetHighWater(_AreaHandle: PAreaHandle; _HighWater: dword): sword; cdecl;
{: Retrieves the length of the message body for the specified message.
@param MsgHandle is a message handle, as returned by MsgOpenMsg.
@returns the length of the body on success. On error, it returns (dword)-1
and sets msgapierr to:
MERR_BADHT }
function MsgGetTextLen(_MsgHandle: PMsgHandle): dword; cdecl;
{: Retrieves the length of the control information for the specified message.
@param MsgHandle is a message handle, as returned by MsgOpenMsg.
@returns the length of the control information on success. On error, it
returns (dword)-1 and sets msgapierr to:
MERR_BADH }
function MsgGetCtrlLen(_MsgHandle: PMsgHandle): dword; cdecl;
{: Initializes the MsgAPI.
This function must be called before any of the other API functions are
called, or else the results are undefined.
This function serves to initialize any needed structures, and to prepare
the message bases for use.
@param MInf is a structure contining the following fields:
record TMInf
// The following fields are required for all
// MsgAPI clients:
word req_version;
word def_zone;
word haveshare;
// The following fields are required when
// req_version >= 1:
void OS2FAR * (MAPIENTRY *palloc)(size_t size);
void (MAPIENTRY *pfree)(void OS2FAR *ptr);
void OS2FAR * (MAPIENTRY *repalloc)(void OS2FAR *ptr,
size_t size);
void far * (MAPIENTRY *farpalloc)(size_t size);
void (MAPIENTRY *farpfree)(void far *ptr);
void far * (MAPIENTRY *farrepalloc)(void far *ptr,
size_t size);
end;
'req_version' indicates the MsgAPI revision level that the application is
requesting. The compile-time revision level can always be
accessed using the constant 'MSGAPI_VERSION'.
'def_zone' should contain a default FidoNet zone number.
Certain message systems, such as the FTSC-0001 *.MSG format,
do not store zone information with each message. When the
API encounters such a message and no zone is present, the
specified zone will be used instead. A 'def_zone' of 0
indicates that nothing is to be inferred about the zone
number of a message, and in that case, the API functions
will return 0 as the zone number for any message with an
unknown zone.
'haveshare' is automatically filled in by the internal API routines, and
this flag indicates whether or not the DOS "SHARE.EXE" program
is currently loaded.
Note that SHARE must always be loaded to access Squish-format
bases in a multitasking or network environment. This field is
not used in the OS/2 version of the MsgAPI.
If 'req_version' is more than or equal to 1, the final six fields in the
_minf structure must be provided. These fields are memory allocation hooks
that MsgAPI will call whenever it needs to allocate memory.
(If req_version is 0, or if one of the function pointers in this structure
is NULL, then MsgAPI will use its own memory allocation routines.)
'palloc' is called to allocate a block of near memory. This function
should behave in the same manner as the ANSI malloc()
function. If this field is NULL, the MsgAPI will use its own
malloc() function.
'pfree' is called to free a block of near memory. This function should
behave in the same manner as the ANSI free() function. If this
field is NULL, the MsgAPI will use its own free() function.
'repalloc' is called to reallocate a block of near memory. This function
should behave in the same manner as the ANSI realloc()
function. If this field is NULL, the MsgAPI will use its own
realloc() function.
'farpalloc' is called to allocate a block of far memory. This function
should behave in the same manner as the ANSI malloc()
function, except that a far pointer should be returned.
If this field is NULL, MsgAPI will use its own malloc()
function.
'farpfree' is called to free a block of far memory. This function should
behave in the same manner as the ANSI free() function, except
that a far pointer should be accepted. If this field is NULL,
MsgAPI will use its own free() function.
'farrepalloc' is called to reallocate a block of far memory. This function
should behave in the same manner as the ANSI realloc()
function, except that a far pointer should be accepted and
returned. If this field is NULL, MsgAPI will use its own
realloc() function.
@returns a value of 0 if the initialization was performed successfully,
and -1 if a problem was encountered. }
function MsgOpenApi(_MInf: PMINF): sword; cdecl;
{: Deinitialize theMsgAPI. This function performs any clean-up actions which
may be necessary, including the closing of files and releasing allocated
memory. This function should be called before the application terminates.
@returns a value of 0 if the API was successfully deinitialized,
and -1 otherwise. }
function MsgCloseApi: sword; cdecl;
{: Opens or creates a message area.
@param Name is the name of the message area to open. The contents of this
string are implementation-defined. (See Type for more information.)
@param Mode is the mode with which the area should be opened. Values for
Mmode are as follows:
MSGAREA_NORMAL Open the message area in a normal access mode. If
the area does not exist, this function fails.
MSGAREA_CRIFNEC Open the message area in a normal access mode.
If the area does not exist, the MsgAPI attempts
to create the area. If the area cannot be created,
this function fails.
MSGAREA_CREATE Create the message area. If the area already exists,
it is truncated or started anew with no messages.
If the area cannot be created, this function fails.
@param Type specifies the type of message area to open. Type can have any of
the following values:
MSGTYPE_SDM Star Dot MSG (SDM). This specifies a FTSC-0001
compatible access mode, and it instructs the MsgAPI
to create and read Fido-compatible messages for
this area. If MSGTYPE_SDM is specified, Name should
contain the path to the *.MSG directory.
MSGTYPE_SQUISH Squish (*.SQ?) format. This specifies that the
proprietary Squish message format is to be used
for this area. Name should give the path and root
name (eight characters in DOS) for the message area.
In addition, if the mask 'MSGTYPE_ECHO' is bitwise 'OR'ed with the '
'MSGTYPE_SDM' value, the area in question will be treated as a
FidoNet-style echomail area. This instructs the MsgAPI to keep
high-water mark information in the 1.MSG file, and to stop the normal
MsgAPI functions from writing to the first message in each area.
Other message formats have a cleaner way of storing the high-water
mark, so this mask is only required for *.MSG areas.
Other values for Type' are currently reserved.
@returns a HAREA handle on success. This handle does not contain any
information which can be used directly by the caller; all
interaction should be performed through the MsgAPI functions only.
If this function fails, NULL is returned, and the global MsgApiErr
variable is set to one of the following values:
MERR_NOMEM Not enough memory for requested task
MERR_NOENT The area did not exist or could not be created.
MERR_BADF The message area is structurally damaged. }
function MsgOpenArea(_Name: PChar; _Mode: sword; _Type: sword): PAreaHandle; cdecl;
{: The MsgValidate function validates a particular message area, determining
whether or not the area exists and if it is valid.
@param Type is the type of the message area, using the same constants as
specified for MsgOpenArea.
@param Name is the name of the message area, using the same format as
specified for MsgOpenArea.
@returns the value 1 if the area exists and is valid. 0 otherwise. }
function MsgValidate(_Type: sword; _Name: PChar): sword; cdecl;
{: This function is not part of the original MsgApi and therefore I don't have
any clue what it does. }
function MsgBrowseArea(b: PBROWSE): sword; cdecl;
function MsgCurMsg(_AreaHandle: PAreaHandle): integer;
function MsgNumMsg(_AreaHandle: PAreaHandle): integer;
function MsgHighMsg(_AreaHandle: PAreaHandle): integer;
function MsgGetCurMsg(_AreaHandle: PAreaHandle): integer;
function MsgGetNumMsg(_AreaHandle: PAreaHandle): integer;
function MsgGetHighMsg(_AreaHandle: PAreaHandle): integer;
function InvalidMsgh(msgh: PMsgHandle): sword; cdecl;
function InvalidMh(mh: PAreaHandle): sword; cdecl;
procedure SquishSetMaxMsg(sq: PAreaHandle; max_msgs: dword; skip_msgs: dword; age: dword); cdecl;
function SquishHash(f: PChar): dword; cdecl;
function SdmOpenArea(name: PChar; mode: sword; _type: sword): PAreaHandle; cdecl;
function SdmValidate(name: PChar): sword; cdecl;
function SquishOpenArea(name: PChar; mode: sword; _type: sword): PAreaHandle; cdecl;
function SquishValidate(name: PChar): sword; cdecl;
function JamOpenArea(name: PChar; mode: sword; _type: sword): PAreaHandle; cdecl;
function JamValidate(name: PChar): sword; cdecl;
function CvtCtrlToKludge(ctrl: PChar): PChar; cdecl;
function GetCtrlToken(where: PChar; what: PChar): PChar; cdecl;
function CopyToControlBuf(txt: PChar; newtext: PPChar; length: PLongInt): PChar; cdecl;
procedure ConvertControlInfo(ctrl: PChar; orig: PNETADDR; dest: PNETADDR); cdecl;
function NumKludges(txt: PChar): sword; cdecl;
procedure RemoveFromCtrl(ctrl: PChar; what: PChar); cdecl;
function Address(a: PNETADDR): PChar; cdecl;
function StripNasties(str: PChar): PChar; cdecl;
implementation
const LIBSMAPI_NAME = 'smapimvc.dll';
function MsgCloseArea(_AreaHandle: PAreaHandle): sword; cdecl;
begin
MsgCloseArea := _AreaHandle^.api^.CloseArea(_AreaHandle);
end;
function MsgOpenMsg(_AreaHandle: PAreaHandle; _Mode: sword; _MsgNum: dword): PMsgHandle; cdecl;
begin
MsgOpenMsg := _AreaHandle^.api^.OpenMsg(_AreaHandle, _Mode, _MsgNum);
end;
function MsgCloseMsg(_MsgHandle: PMsgHandle): sword; cdecl;
begin
MsgCloseMsg := _MsgHandle^.sq^.api^.CloseMsg(_MsgHandle);
end;
function MsgReadMsg(_MsgHandle: PMsgHandle; _XMsg: PXMSG; _Offset: dword;
_BodyLen: dword; _Body: PChar; _ControlLen: dword; _Control: PChar): integer; cdecl;
begin
MsgReadMsg := _MsgHandle^.sq^.api^.ReadMsg(_MsgHandle, _XMsg, _Offset,
_BodyLen, _Body, _ControlLen, _Control);
end;
function MsgWriteMsg(_MsgHandle: PMsgHandle; _Append: sword; _Xmsg: PXMSG;
_Body: PChar; _Bodylen: dword; _Total: dword; _ControlLen: dword; _Control: PChar): sword; cdecl;
begin
MsgWriteMsg := _MsgHandle^.sq^.api^.WriteMsg(_MsgHandle, _Append, _Xmsg,
_Body, _Bodylen, _Total, _ControlLen, _Control);
end;
function MsgKillMsg(_AreaHandle: PAreaHandle; _MsgNum: dword): sword; cdecl;
begin
MsgKillMsg := _AreaHandle^.api^.KillMsg(_AreaHandle, _MsgNum);
end;
function MsgLock(mh: PAreaHandle): sword; cdecl;
begin
MsgLock := mh^.api^.Lock(mh);
end;
function MsgUnLock(mh: PAreaHandle): sword; cdecl;
begin
MsgUnLock := mh^.api^.UnLock(mh);
end;
function MsgSetCurPos(_MsgHandle: PMsgHandle; _Pos: dword): sword; cdecl;
begin
MsgSetCurPos := _MsgHandle^.sq^.api^.SetCurPos(_MsgHandle, _Pos);
end;
function MsgGetCurPos(_MsgHandle: PMsgHandle): dword; cdecl;
begin
MsgGetCurPos := _MsgHandle^.sq^.api^.GetCurPos(_MsgHandle);
end;
function MsgMsgnToUid(_AreaHandle: PAreaHandle; _MsgNum: dword): TUMsgId; cdecl;
begin
MsgMsgnToUid := _AreaHandle^.api^.MsgnToUid(_AreaHandle, _MsgNum);
end;
function MsgUidToMsgn(_AreaHandle: PAreaHandle; _UMsgId: TUMsgId;
_Type: sword): dword; cdecl;
begin
MsgUidToMsgn := _AreaHandle^.api^.UidToMsgn(_AreaHandle, _UMsgId, _Type);
end;
function MsgGetHighWater(_AreaHandle: PAreaHandle): dword; cdecl;
begin
MsgGetHighWater := _AreaHandle^.api^.GetHighWater(_AreaHandle);
end;
function MsgSetHighWater(_AreaHandle: PAreaHandle; _HighWater: dword): sword; cdecl;
begin
MsgSetHighWater := _AreaHandle^.api^.SetHighWater(_AreaHandle, _HighWater);
end;
function MsgGetTextLen(_MsgHandle: PMsgHandle): dword; cdecl;
begin
MsgGetTextLen := _MsgHandle^.sq^.api^.GetTextLen(_MsgHandle);
end;
function MsgGetCtrlLen(_MsgHandle: PMsgHandle): dword; cdecl;
begin
MsgGetCtrlLen := _MsgHandle^.sq^.api^.GetCtrlLen(_MsgHandle);
end;
// Thes functions aren't actually functions, they are just wrappers to
// access some fields in the AreaHandle in a controlled way.
// in C they are macros.
function MsgCurMsg(_AreaHandle: PAreaHandle): integer;
begin
Result := _AreaHandle^.cur_msg;
end;
function MsgGetCurMsg(_AreaHandle: PAreaHandle): integer;
begin
Result := _AreaHandle^.cur_msg;
end;
function MsgNumMsg(_AreaHandle: PAreaHandle): integer;
begin
Result := _AreaHandle^.num_msg;
end;
function MsgGetNumMsg(_AreaHandle: PAreaHandle): integer;
begin
Result := _AreaHandle^.num_msg;
end;
function MsgHighMsg(_AreaHandle: PAreaHandle): integer;
begin
Result := _AreaHandle^.high_msg;
end;
function MsgGetHighMsg(_AreaHandle: PAreaHandle): integer;
begin
Result := _AreaHandle^.high_msg;
end;
function MsgGetMsgApiErr: sword; cdecl; external LIBSMAPI_NAME name 'MsgGetMsgApiErr';