home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / pocketbk / utilsu / wld / WLD.DOC < prev   
Text File  |  1992-05-04  |  7KB  |  287 lines
  1. WORLD DEVICE DRIVER INTERFACE (WLD:)
  2. ====================================
  3.  
  4. Some definitions
  5. ----------------
  6.  
  7. #define WR_FIND_CITY 10
  8. #define WR_FIND_COUNTRY 11
  9. #define WR_FIND_EXACT 12
  10. #define WR_NEXT 13
  11. #define WR_BACK 14
  12. #define WR_GET_HOME 15
  13. #define WR_SET_HOME 16
  14. #define WR_GET_DEFAULT_COUNTRY 17
  15. #define WR_SET_DEFAULT_COUNTRY 18
  16. #define WR_GET_DIAL_STRING 19
  17. #define WR_EXTRA 20
  18. #define WR_SET_EXTRA 21
  19. #define WR_GET_CITY_DATA 22
  20. #define WR_GET_COUNTRY_DATA 23
  21. #define WR_CALC 24
  22. #define WR_NEXT_LOCK 25
  23.  
  24. #define WR_MAX_NAME 20
  25. #define WR_MAX_DIAL 16
  26. #define WR_MAX_CODE 8
  27. #define WR_MAX_INTRA 4
  28. #define WR_MAX_INTER 4
  29. #define WR_MAX_DIAL_STRING 24
  30. #define WR_MAX_IN_STRING 64
  31.  
  32. #define WR_UNITS_MILES 0
  33. #define WR_UNITS_KILOMETERS 1
  34. #define WR_UNITS_NAUTICAL 2
  35.  
  36. #define WR_START_STATE 1
  37. #define WR_END_STATE 0
  38.  
  39. #define WR_NOT_FOUND E_GEN_FAIL
  40. #define WR_FOUND 0
  41.  
  42. #define WR_EXTRA_ADD_CITY 0
  43. #define WR_EXTRA_UPDATE_CITY 1
  44. #define WR_EXTRA_DELETE_CITY 2
  45. #define WR_EXTRA_UPDATE_COUNTRY 3
  46. #define WR_EXTRA_ADD_HOME 4
  47.  
  48. #define WR_DELETED 0
  49. #define WR_REVERTED 1
  50.  
  51. #define WR_TOO_MANY_ERR -23
  52. #define WR_NOTVALID_ERR -25
  53. #define WR_DELHOME_ERR -26
  54. #define WR_DELCAPITAL_ERR -27
  55. #define WR_DUPLICATE_ERR -28
  56.  
  57. typedef struct /* Lat long */
  58.     {
  59.     WORD  iLat;
  60.     WORD  iLong;
  61.     } LATL;
  62.  
  63. typedef struct
  64.     {
  65.     TEXT city[WR_MAX_NAME+1];
  66.     TEXT country[WR_MAX_NAME+1];
  67.     } WR_FIND_RES;
  68.  
  69. typedef struct
  70.     {
  71.     WR_FIND_RES f;
  72.     UBYTE units; /* Also baseGMT */
  73.     UBYTE DST;
  74.     WORD GMT;
  75.     LATL latl;
  76.     TEXT dial[WR_MAX_DIAL+1];
  77.     TEXT STD[WR_MAX_CODE+1];
  78.     P_POINT pos;
  79.     } WR_CITY_DATA;
  80.  
  81. typedef struct
  82.     {
  83.     TEXT dialIntra[WR_MAX_INTRA+1];
  84.     TEXT dialInter[WR_MAX_INTER+1];
  85.     TEXT dial[WR_MAX_CODE+1];
  86.     UBYTE dummy;
  87.     } CO_DIAL;
  88.  
  89. typedef struct
  90.     {
  91.     WR_FIND_RES f;
  92.     BYTE baseGMT;
  93.     UBYTE DST;
  94.     WORD GMT;
  95.     CO_DIAL dial;
  96.     } WR_COUNTRY_DATA;
  97.  
  98. typedef union
  99.     {
  100.     WR_CITY_DATA ci;
  101.     WR_COUNTRY_DATA co;
  102.     } WR_EXTRA_DATA;
  103.  
  104. typedef struct
  105.     {
  106.     WORD distance;
  107.     WORD sunRise;
  108.     WORD sunSet;
  109.     WORD always;
  110.     } WR_CALC_OUT;
  111.  
  112. typedef union
  113.     {
  114.     WR_CITY_DATA in;
  115.     WR_CALC_OUT out;
  116.     } WR_CALC_DATA;
  117.  
  118. Some documentation
  119. ------------------
  120.  
  121. The world device driver can be opened with the following call:
  122.  
  123.     INT ret;
  124.     VOID *w;
  125.     ret=p_open(&w,"wld:",0xffff);
  126.  
  127. and all i/o functions can be requested using p_ioa(), p_ioc() or
  128. p_iow(). At all times an open channel is always positioned on a valid
  129. city or country.
  130.  
  131. All other functionality is as described below:
  132.  
  133.  
  134. INT WR_FIND_CITY(TEXT *match,WR_FIND_RES *result)
  135.  
  136. Match is in 'match'.  Max size WR_MAX_NAME.  Text can be
  137. any case - a fold is automatically done.
  138. Return WR_NOT_FOUND or WR_FOUND.
  139. If not found then previous position is restored.
  140.  
  141.  
  142. INT WR_FIND_COUNTRY(TEXT *match,WR_FIND_RES *result)
  143.  
  144. Match is in 'match'. Max size WR_MAX_NAME. Text can be
  145. any case - a fold is automatically done.
  146. Return WR_NOT_FOUND or WR_FOUND.
  147. If not found then previous position is restored.
  148.  
  149.  
  150. INT WR_FIND_EXACT(WR_FIND_RES *match)
  151.  
  152. Match is in 'match'. Matches to the city. Text can be any
  153. case - a fold is automatically done. If no city string is
  154. given a country search is performed.
  155. Return WR_NOT_FOUND or WR_FOUND.
  156. If not found then previous status is restored.  On success the type
  157. (for NEXT etc) is city or country depending on whether the city field
  158. was null.
  159.  
  160.  
  161. VOID WR_NEXT(WR_FIND_RES *result)
  162.  
  163. No input parameters.
  164.  
  165.  
  166. VOID WR_BACK(WR_FIND_RES *result)
  167.  
  168. No input parameters.
  169. VOID WR_GET_HOME(WR_FIND_RES *result)
  170.  
  171. No input parameters. The type (for NEXT etc) is city.
  172.  
  173.  
  174. INT WR_SET_HOME(VOID)
  175.  
  176. No input parameters. Returns WR_NOTVALID_ERR if item no longer valid.
  177.  
  178.  
  179. VOID WR_GET_DEFAULT_COUNTRY(WR_FIND_RES *result)
  180.  
  181. No input parameters. The type (for NEXT etc) is city.
  182.  
  183.  
  184. INT WR_SET_DEFAULT_COUNTRY(VOID)
  185.  
  186. No input parameters. Returns E_GEN_UNDER if item no longer valid.
  187.  
  188.  
  189. INT WR_GET_DIAL_STRING(TEXT *inString,TEXT *outString)
  190.  
  191. Input in 'inString'. Output in 'outString'. Can fail with
  192. E_GEN_ARG (null string, missing ']' after '[' or country
  193. name not found). Limit of P_FNAMESIZE for the input
  194. string.  Output buffer must allow for
  195. WR_MAX_DIAL_STRING+1 bytes, returns E_GEN_OVER if it is
  196. too long.  Intelligent handling is done if the there is a
  197. space or '-' embedded in the number.
  198.  
  199.  
  200. INT WR_EXTRA(WORD *func,WR_EXTRA_DATA *data)
  201.  
  202. Function number in 'func' and new data in 'data'.  'data'
  203. is not required for DELETE. Can fail because of p_alloc
  204. errors so can return system errors or the specific errors
  205. listed below.  No data checking is performed.
  206.  
  207. This function requires a file to have been opened with
  208. WR_SET_EXTRA and for there to be enough room on the media
  209. for the operation.  The standard default file is
  210. \WLD\WORLD.WLD.
  211.  
  212. Returns WR_NOTVALID_ERR if item is no longer valid.
  213.  
  214. WR_EXTRA_ADD_CITY
  215.  
  216. Returns E_GEN_ARG if it fails to match the country string
  217. to a country.  Returns WR_DUPLICATE_ERR if the
  218. city/country matches an existing city/country. Returns
  219. WR_TOO_MANY_ERR if more than 32 items are already
  220. present.
  221.  
  222. WR_EXTRA_UPDATE_CITY
  223. Returns E_GEN_ARG if it fails to match the country text
  224. to a country.  Returns WR_DUPLICATE_ERR if the
  225. city/country matches an existing city/country (which it
  226. is not being updated).
  227.  
  228. WR_EXTRA_DELETE_CITY
  229.  
  230. Returns WR_NOT_VALID if current item is not an extra
  231. city, WR_DELHOME_ERR if the item is the current home,
  232. WR_DELCAPITAL_ERR if the item is an added capital city.
  233. Returns either WR_REVERTED or WR_DELETED depending on
  234. whether it was an added on updated item.
  235.  
  236. WR_EXTRA_UPDATE_COUNTRY
  237.  
  238. Returns E_GEN_ARG if the capital string does not match an
  239. existing city in the country being updated or if the new
  240. country name conflicts with an existing country.  All
  241. city GMTs in extra for that country will be adjusted.
  242. They will also take the new DST.
  243.  
  244.  
  245. INT WR_SET_EXTRA(WORD *flag,TEXT *name)
  246.  
  247. Flag is in 'flag' and name is in 'name'.  Returns system
  248. errors and E_GEN_IMAGE if the file is badly formatted or
  249. has a different database version number.  The name is
  250. parsed with the extension '.WLD'.
  251.  
  252. P_FOPEN
  253.  
  254. Fails if files does not exist or can not be opened. If it
  255. is badly formatted it returns E_GEN_IMAGE.  If the
  256. current item is in the extra database it becomes invalid
  257. (though NEXT & BACK will work but any function using the
  258. current position will fail).  For example
  259. WR_GET_CITY_DATA will give the error E_GEN_UNDER.
  260.  
  261. P_FREPLACE
  262.  
  263. Fails if can not replace/create the file.
  264.  
  265.  
  266. INT WR_GET_CITY_DATA(WR_CITY_DATA *result)
  267.  
  268. No input parameters. Returns WR_NOTVALID_ERR if item no
  269. longer valid.
  270.  
  271.  
  272. INT WR_GET_COUNTRY_DATA(WR_COUNTRY_DATA *result)
  273.  
  274. No input parameters. Returns WR_NOTVALID_ERR if item no longer valid.
  275. INT WR_CALC(WORD *state,WR_CALC_DATA *calc)
  276.  
  277. Input state in 'wFlag', and when 'state' ==
  278. WR_START_STATE data is in 'calc'. On 'state' ==
  279. WR_END_STATE result is returned to 'calc'. New state
  280. always returned in wFlag.  Can return system errors (eg
  281. E_GEN_NOMEMORY).
  282.  
  283.  
  284. VOID WR_NEXT_LOCK(WR_FIND_RES *result)
  285.  
  286. Returns the next city in the current country.
  287.