home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 4 / AACD04.ISO / AACD / Programming / PMM / Doku / LibsDoku / GatewayLibraryENG.readme < prev    next >
Encoding:
Text File  |  1999-10-20  |  13.5 KB  |  622 lines
  1. Sorry, a full english version of the guide not exists.
  2. My english isn't good enough to create a guide or doc.
  3.  
  4. But I will do this shot readme to give a litte help and hope
  5. you understand it:
  6.  
  7. At first, a lot of backgroundinformation's are in the german document.
  8. A typical copyright with full permission to use. The archive must been
  9. original if you give the archive to another person. Commercial use is
  10. forbidden.
  11. And, a very importand information: Gateway-5 is a BBS-Programm, based
  12. on Gateway-IV and so on. The first program only called Gateway. For over
  13. 10 Years! Now, the owner of the Amiga call Gateway, too. But, my program
  14. and "Gateway 2000" have only the same name, not more!
  15.  
  16.  
  17. The functions in this library are created in the last 10 years. For
  18. different programs and differnt usage. So the names of the variables
  19. are very differnt.
  20. All functions are everytime backward compatible. And so the one or
  21. another is not perfect or locks very fine. But, all functions work
  22. correct and the functions that use they often long time not changed.
  23. The program was written on Aztec-C in the past and as I changed the old
  24. compiler to vbcc there are not all functions available. Functions that
  25. be used in gateway or gateway-tools an missed on vbcc are rebuild and
  26. all that functions includes in this library. Only the functions that
  27. use directly DOS-functions are in an external link-library (like unlink).
  28.  
  29.  
  30. The library.functions:
  31. __________________________________________________________________________
  32.  
  33. ULONG GateRequest(UBYTE *title_d1,UBYTE *body,UBYTE *gadgets);
  34.  
  35. Testfunction, work the library? Link to EasyRequest.
  36.  
  37. in:
  38. ---
  39. UBYTE *title_d1  - headline requester
  40. UBYTE *body      - body of requester
  41. UBYTE *gadgets   - text for gadgets
  42.  
  43.  
  44. back:
  45. -----
  46. ULONG            - the gadgetnumber
  47.  
  48. __________________________________________________________________________
  49.  
  50. char *ltofa(char *tx_d1,ULONG l);
  51.  
  52. (Long TO formatted ascii)
  53.  
  54. Function to format a ULONG like this:
  55.  
  56. 1234567890 => '1.234.567.890'
  57. 482        => '          482'
  58. 48526      => '       48.526'
  59.  
  60.  
  61. in:
  62. ---
  63. char  *tx_d1      - pointer to string (min. 14 chars)
  64. ULONG  l          - the ulong to format
  65.  
  66.  
  67. back:
  68. -----
  69. char  *           - pointer to tx_d1
  70.  
  71. __________________________________________________________________________
  72.  
  73. void trim(UBYTE *trptr);
  74.  
  75. strip all blank's left and right on the string.
  76.  
  77. in:
  78. ---
  79. UBYTE  *trtpr     - string to be cleared
  80.  
  81.  
  82. back:
  83. -----
  84. N/A
  85.  
  86. __________________________________________________________________________
  87.  
  88. void trim_cr(UBYTE *trptr);
  89.  
  90. strip all blank's, CTRL-n, CR and LF left and right on the string.
  91.  
  92. in:
  93. ---
  94. UBYTE  *trtpr     - string to be cleared
  95.  
  96.  
  97. back:
  98. -----
  99. N/A
  100.  
  101. __________________________________________________________________________
  102.  
  103. void rtrim(UBYTE *trptr);" @{uu}@{LINDENT 6}
  104.  
  105. same as trim, but clear only the right side of the string.
  106.  
  107. in:
  108. ---
  109. UBYTE  *trtpr     - Pointer auf den String der bereinigt wird. Nach dem Funktionsaufruf ist der String bereinigt.
  110.  
  111.  
  112. back:
  113. -----
  114. N/A
  115.  
  116. __________________________________________________________________________
  117.  
  118. void lset(UBYTE *lbuff, int slen);
  119.  
  120. format a string to slen-chars.
  121. if the string is smaller: fill at left side with spaces.
  122. if the string is greater: cut right side
  123.  
  124. in:
  125. ---
  126. UBYTE  *lbuff    - pointer to string
  127. int     slen     - len the string have on return
  128.  
  129.  
  130. back:
  131. -----
  132. N/A
  133.  
  134. __________________________________________________________________________
  135.  
  136. void lsetmin(UBYTE *lbuff, int slen);
  137.  
  138. same as lset, but fill only the string, don't cut!
  139.  
  140. in:
  141. ---
  142. UBYTE  *lbuff    - pointer to string
  143. int     slen     - minimal len of string
  144.  
  145.  
  146. back:
  147. -----
  148. N/A
  149.  
  150. __________________________________________________________________________
  151.  
  152. void string(UBYTE *spstr, int num, int ch);
  153.  
  154. fill string *spstr with character ch at a len of num bytes.
  155.  
  156. in:
  157. ---
  158. UBYTE  *spstr    - pointer of string to be filled
  159. int     num      - len of string to be filled
  160. int     ch       - the character that will be used to fill
  161.  
  162.  
  163. back:
  164. -----
  165. N/A
  166.  
  167. __________________________________________________________________________
  168.  
  169. int instr(UBYTE *sa, UBYTE *sb);
  170.  
  171. search sb in sa and give back the position where sb found in sa.
  172. The position is 0 upto strlen(sa)-strlen(sb).
  173. -1 if not found.
  174. The case of the chars is not relevant (both strings will test uppercase or
  175. lowercase). The function do that for german chars, also ä, ö and ü will
  176. same as Ä, Ö and Ü.
  177.  
  178. in:
  179. ---
  180. UBYTE  *sa       - big string to search on
  181. UBYTE  *sb       - the searched string
  182.  
  183.  
  184. back:
  185. -----
  186. int              - positionwhre sb found or -1 if not
  187.  
  188. __________________________________________________________________________
  189.  
  190. int instr_pat(UBYTE *sa, UBYTE *sb);
  191.  
  192. same as instr but also pattern matching. * for any string and ? for any
  193. character.
  194.  
  195. in:
  196. ---
  197. UBYTE  *sa       - big string to search on
  198. UBYTE  *sb       - the searched string
  199.  
  200.  
  201. back:
  202. -----
  203. int              - positionwhre sb found or -1 if not
  204.  
  205. __________________________________________________________________________
  206.  
  207. void upstr(UBYTE *trptr);
  208.  
  209. make string uppercase including ä -> Ä, ö -> Ö and ü -> Ü
  210.  
  211. in:
  212. ---
  213. UBYTE  *trptr   - pointer to string
  214.  
  215.  
  216. back:
  217. -----
  218. N/A
  219.  
  220. __________________________________________________________________________
  221.  
  222. void lowstr(UBYTE *trptr);
  223.  
  224. make string lowercase including Ä -> ä, Ö -> ö and Ü -> ü
  225.  
  226. in:
  227. ---
  228. UBYTE  *trptr   - pointer to string
  229.  
  230. back:
  231. -----
  232. N/A
  233.  
  234. __________________________________________________________________________
  235.  
  236. void set(UBYTE *lbuff, int slen);
  237.  
  238. string will be return with len = slen.
  239. if the string is longer than slen, it will be cut
  240. if the string is to short blanks will be add at the end of string
  241.  
  242.  
  243. in:
  244. ---
  245. UBYTE  *lbuff   - pointer to string
  246. int     slen    - len for the string when returns
  247.  
  248.  
  249. back:
  250. -----
  251. N/A
  252.  
  253. __________________________________________________________________________
  254.  
  255. void midstr(UBYTE *mstr, int pos, long laenge);
  256.  
  257. cut a part (substring) from the string.
  258. pos is the beginning position ( 0-(strlen-1) ) and laenge means how many
  259. bytes will be cut. laenge=-1 means, from pos to end of string.
  260.  
  261.  
  262. in:
  263. ---
  264. UBYTE  *mstr    - pointer of string
  265. int     pos     - begin of substring
  266. int     laenge  - len for the substring or -1
  267.  
  268.  
  269. back:
  270. -----
  271. N/A
  272. __________________________________________________________________________
  273.  
  274. ULONG date_to_day(ULONG date);
  275.  
  276. Give the day in the year (1-365) for 'date'.
  277. This function isn't exact, it will only +/- 2 day's near the right,
  278. because it is only used for a cruncherfunction in the bbs-system that
  279. killed to old things.
  280.  
  281.  
  282.  
  283. in:
  284. ---
  285. ULONG date      - Date as ULONG in format ttmmjjjj
  286.  
  287.  
  288. back:
  289. -----
  290. ULONG           - day in year (1-365 +/-2 days)
  291.  
  292. __________________________________________________________________________
  293.  
  294. ULONG date_to_zahl(UBYTE *da);
  295.  
  296. Date from string to ULONG.
  297. Stringformat = TT.MM.JJJJ
  298. ULONG        = TTMMJJJJ
  299.  
  300.  
  301. in:
  302. ---
  303. UBYTE *da       - Date in format tt.mm.jjjj (the points can be any char)
  304.                   example: tt-mm-jjjj is also correct
  305.  
  306.  
  307. back:
  308. -----
  309. ULONG           - Date as ULONG=ttmmjjjj
  310.  
  311. __________________________________________________________________________
  312.  
  313. ULONG time_to_zahl(UBYTE *ti);
  314.  
  315. Time from string to ULONG
  316. A time in form SS:mm:ss will be returned as ULONG.
  317. The returned time can betwen 1 and 6 digits
  318. 00:00:07 = one, 10:10:05 = six
  319.  
  320.  
  321. in:
  322. ---
  323. UBYTE  *ti      - Time in SS:mm:ss (: can by any char)
  324.                   example: SS/mm/ss is also correct
  325.  
  326.  
  327. back:
  328. -----
  329. ULONG           - time as ULONG=SSmmss
  330.  
  331. __________________________________________________________________________
  332.  
  333. void kill_ansi(UBYTE *buffer);
  334.  
  335. delete most ansi-sequences from a string. Because this finction only need
  336. to delete cursor-functions and colors it search a character as end for a
  337. ansi-sequence. ansi-codes that end with special-characters are cut to
  338. many chars.
  339.  
  340.  
  341. in:
  342. ---
  343. UBYTE  *buffer  - pointer of string
  344.  
  345.  
  346. back:
  347. -----
  348. N/A
  349.  
  350. @ENDNODE
  351.  
  352. @NODE "newer" "newer"
  353. @{LINDENT 3}
  354. BOOL newer(UBYTE *d1, UBYTE *t1, UBYTE *d2, UBYTE *t2);
  355.  
  356. Is date d1 and time t1 NEWER than date d2 and time t2
  357.  
  358.  
  359. in:
  360. ---
  361. UBYTE  *d1     - 1. date in format tt.mm.jjjj
  362. UBYTE  *t1     - 1. time in format SS:mm:ss
  363. UBYTE  *d2     - 2. date in format tt.mm.jjjj
  364. UBYTE  *t2     - 2. time in format SS:mm:ss
  365.  
  366.  
  367. back:
  368. -----
  369. BOOL           - TRUE if the first set is newer as the second
  370.  
  371. __________________________________________________________________________
  372.  
  373. void swapmem(char *src, char *dst, int n);
  374.  
  375. swap a memoryblock of n bytes.
  376.  
  377.  
  378. in:
  379. ---
  380. char   *src    - pointer to first memoryblock.
  381. char   *dst    - pointer to second memoryblock.
  382. int     n      - how many bytes to be swapped
  383.  
  384.  
  385. back:
  386. -----
  387. N/A
  388.  
  389. __________________________________________________________________________
  390.  
  391. int memncmp(char *a, char *b, int length);
  392.  
  393. Compare to memoryblock's of n bytes
  394.  
  395.  
  396. in:
  397. ---
  398. char   *a      - pointer auf 1. memoryblock
  399. char   *b      - pointer auf 2. momoryblock
  400. int     lenght - how many bytes to be compare
  401.  
  402.  
  403. back:
  404. -----
  405. int            -  0 if equal
  406.                   1 if a > b
  407.                  -1 if a < b
  408.  
  409. __________________________________________________________________________
  410.  
  411. int StrCaseCmp(char *s1, char *s2);
  412.  
  413. Compare two strings (both as lower or upper). But german characters NOT
  414. convert, also ä not equal Ä.
  415.  
  416.  
  417. in:
  418. ---
  419. char   *s1     - pointer of 1. string
  420. char   *s2     - pointer of 2. String.
  421.  
  422.  
  423. back:
  424. -----
  425. int            -  0 if equal
  426.                   1 if not equal
  427. __________________________________________________________________________
  428.  
  429. void trim_includes(UBYTE *trptr);
  430.  
  431. see trim.
  432. this is a special-version that delete all what not be a part of a filename
  433. at begin and end of the string.
  434. pmm use this to isolate the includepath- and filename
  435.  
  436.  
  437. in:
  438. ---
  439. UBYTE  *trtpr     - pointer of string
  440.  
  441.  
  442. back:
  443. -----
  444. N/A
  445.  
  446. __________________________________________________________________________
  447.  
  448. void trim_includes(UBYTE *trptr, int fkt);
  449.  
  450. see trim.
  451. this specail-version delete all, what not be part of an emailadress
  452.  
  453.  
  454. in:
  455. ---
  456. UBYTE  *trtpr     - pointer of string
  457. int     fkt       - 1, if < and > will deleted
  458.                     0, if < and > not deleted
  459.  
  460. back:
  461. ----
  462. N/A
  463.  
  464. __________________________________________________________________________
  465.  
  466. void newstr(UBYTE *istr, UBYE *nstr, int pos, int len);
  467.  
  468.  
  469. that is the point who my english will be a problem. anyway:
  470. a part of istr will be cut. the same place will be filled with nstr.
  471. the len of nstr can be smaller, equal or greater than the part that
  472. will cut.
  473. the part to cut begin at 'pos' and has 'len' bytes.
  474.  
  475. The name istr come from the function that first use this function.
  476. It was the interpreter in the bbs-software.
  477.  
  478.  
  479.  
  480.  
  481. in:
  482. ---
  483. UBYTE  *istr      - pointer of string that will be changed
  484. UBYTE  *nstr      - pointer of new substring ("" will only cut)
  485. int     pos       - position to begin change
  486. int        len       - how many bytes changed (0 will only insert nstr)
  487.  
  488.  
  489.  
  490. back:
  491. -----
  492. N/A
  493.  
  494. __________________________________________________________________________
  495.  
  496. int wordwrp(UBYTE *line, UBYTE *rest, int len);
  497.  
  498. edit-sub-function
  499.  
  500. if line len or more bytes the function look for a blank in line[len] to
  501. line[len-20]. If a blank found, line will be cut at the blank an the
  502. right part is put to rest. If line shorter than len or not blank is
  503. found nothing happend with line and rest is return as char zero.
  504.  
  505.  
  506. in:
  507. ---
  508. UBYTE  *line      - string to check
  509. UBYTE  *rest      - if line cut the cutted-part is returned here. Else a
  510.                     char zero.
  511. int        len       - maximum len of line
  512.  
  513.  
  514. back:
  515. -----
  516. int                  - 0 = if nothing done
  517.                     1 = if cut and rest is filled
  518. __________________________________________________________________________
  519.  
  520. void fn_splitt(char *src, char *drive, char *path, char *name, char *ext);
  521.  
  522. Spliting the string src (a filename with full path) in the parts
  523. drive
  524. path
  525. filename (without extension)
  526. extension of filename
  527. All parts that not exits will be returned als char zero.
  528.  
  529.  
  530.  
  531. in:
  532. ---
  533. char   *src       - pointer of source-string
  534. char   *drive     - back drive
  535. char   *path      - back path
  536. char   *name      - back filename
  537. char   *ext       - back extension of filename
  538.  
  539.  
  540. back:
  541. -----
  542. char   *          - pointer to src
  543.  
  544. __________________________________________________________________________
  545.  
  546. void fn_build(char *dst, char *drive, char *path, char *name, char *ext);
  547.  
  548. cat all part's to a filename with full path.
  549.  
  550. drive must be end with :
  551. path can be end with or wthout /, if not, it will inserted
  552. name
  553. extension (beginning with a point, if not, it will be inserted.
  554.  
  555. If any part is empty, it will skip. If path empty no / inserted and if
  556. extension empty no point inserted.
  557.  
  558.  
  559. in:
  560. ---
  561. char   *dst       - the completed filename
  562. char   *drive     - drive:
  563. char   *path      - path[/]
  564. char   *name      - filename
  565. char   *ext       - [.]extension
  566.  
  567.  
  568. back:
  569. -----
  570. char   *          - pointer to dst
  571.  
  572. __________________________________________________________________________
  573.  
  574. void addval(UBYTE *str, ULONG n);
  575.  
  576. add the ULONG n to str (formatted 10 digits, left side filled with blank
  577.  
  578.  
  579. in:
  580. ---
  581. char   *addval    - string (10 bytes), numeric chars
  582.                     formatstring is %10lu
  583. ULONG   n         - value that add to the value in the string.
  584.  
  585.  
  586. back:
  587. -----
  588. N/A
  589.  
  590. __________________________________________________________________________
  591.  
  592. char *strdup(char *s);
  593.  
  594. return a duplicate of string s
  595.  
  596.  
  597. in:
  598. ---
  599. char   *s         - pointer to string
  600.  
  601.  
  602. Rückgabe:
  603. ---------
  604. char   *          - pointer of the copy from s
  605.  
  606. __________________________________________________________________________
  607.  
  608. char *index(const char *str, int c);
  609.  
  610. search the first char that is identical to char c
  611.  
  612.  
  613. in:
  614. ---
  615. const char *s     - pointer of searchable string
  616. int            c     - ascii-vaalue of char that will be searched
  617.  
  618. back:
  619. -----
  620. char   *          - pointer to position of c, if not found 0 returned
  621.  
  622.