home *** CD-ROM | disk | FTP | other *** search
/ Windoware / WINDOWARE_1_6.iso / winutil / intl / intlapi.txt < prev    next >
Text File  |  1992-04-08  |  13KB  |  366 lines
  1. The functions in the INTL dll.
  2.  
  3.  
  4. IntlVersion
  5. -----------
  6. Syntax:     WORD FAR PASCAL IntlVersion(void)
  7. Description:    This function returns the version of the DLL. Backward
  8.         compatibility is promised.
  9. Parameters:    -
  10. Returns:    The version number. Major version in HIBYTE, and minor
  11.         version in LOBYTE.
  12. Return value:    Currently 0x0100 (i.e. ver 1.0)
  13. Remark:         The macros HIWORD and LOWORD are defined in windows.h
  14.  
  15.  
  16. IntlInit
  17. --------
  18. Syntax:     BOOL FAR PASCAL IntlInit(LPSTR lpLanguage)
  19. Description:    This function initiates the DLL. It should be called
  20.         before any use of the conversion functions (all functions
  21.         except IntlVersion), and when trapping a WM_WININICHANGE
  22.         message indicating a change in the [intl] section of
  23.         WIN.INI.
  24. Parameters:    lpLanguage:    The string in which a copy of the sLanguage
  25.                 variable will be stored.
  26. Returns:        Result of initialization.
  27. Return value:    FALSE if initiation failed
  28.         TRUE on success.
  29. Comment:    The sLanguage variable is a string containing a 3 letter
  30.         abbreviation of the language to use. For example "spa" for
  31.         Spanish or "itn" for Italian. Read WININI2.TXT for more
  32.         information. If the returned string is empty, no language is
  33.         set and you should provide the user a way of selecting a
  34.         language.
  35.  
  36.  
  37. IntlDateToString
  38. ----------------
  39. Syntax:     LPSTR FAR PASCAL IntlDateToString(LPSTR lpString,
  40.                           int    nYear,
  41.                           int    nMon,
  42.                           int    nMday,
  43.                           int    nWday,
  44.                           int    nMode)
  45. Description:    This function converts a date, in year, month, day of month
  46.         and day of week, to a string. The conversion can be either
  47.         to a long or short format.
  48. Parameters:    lpString:    The string in which the result of the
  49.                 conversion will be stored.
  50.         nYear:        as in struct tm.
  51.         nMon:        as in struct tm.
  52.         nMday:        as in struct tm (month day).
  53.         nWday:        as in struct tm (week day).
  54.         nMode:        IntlSHORT or IntlLONG. Anything else gives
  55.                 unpredictable results.
  56. Returns:    lpString
  57. Comment:    There is no check if the date is valid or not.
  58. Remark:         IntlSHORT and IntlLONG are defined in intl.h
  59.  
  60. IntlTimeToString
  61. ----------------
  62. Syntax:     LPSTR FAR PASCAL IntlTimeToString(LPSTR lpString,
  63.                           int    nNour,
  64.                           int    nMin,
  65.                           int    nSec)
  66. Description:    This function converts a time in hours, minutes and seconds
  67.         to a string.
  68. Parameters:    lpString:      The string in which the result of the
  69.                    conversion will be stored.
  70.         nHour:           as in struct tm.
  71.         nMin:           as in struct tm or IntlSKIP.
  72.         nSec:           as in struct tm or IntlSKIP.
  73. Returns:    lpString
  74. Comment:    There is no check if the time is valid or not.
  75.         If a parameter is IntlSKIP the field representing that
  76.         parameter and the fields after that will be ignored.
  77. Remark:         IntlSKIP is defined in intl.h
  78.  
  79.  
  80. IntlFloatToString
  81. -----------------
  82. Syntax:     LPSTR FAR PASCAL IntlFloatToString(LPSTR  lpString,
  83.                            double dVal,
  84.                            int      nMode,
  85.                            size_t nWidth
  86.                            int      nDecimals)
  87. Description:    This function converts a floating point number to a string.
  88.         The conversion can be to any of the formats IntlSTD,
  89.         IntlFIX, IntlSCI, IntlENG or IntlPRE.
  90.  
  91. Parameters:    lpString:   The string in which the result of the conversion
  92.                 will be stored
  93.         dVal:        The floating point number to convert.
  94.         nMode:        The mode to convert to. The modes are:
  95.                 IntlSTD:    The standard conversion. Numbers
  96.                     formatted as xxxx.yyyy. There are
  97.                     two exceptions to this. (1) The number
  98.                     is too large to be contained in the
  99.                     field. (2) The value of the number is
  100.                     so small, it'd be converted to 0.000.
  101.                     In both cases the mode becomes
  102.                     IntlSCI.
  103.                 IntlFIX:    Same as IntlSTD, except the number
  104.                     that are small will be converted to
  105.                     0.000
  106.                 IntlSCI:    Scientific mode. The number will be
  107.                     converted to the x.yyyEz format.
  108.                 IntlENG:    Engineering mode. Like the IntlSCI,
  109.                     but the power of 10 will always be a
  110.                     multiple of 3. The format can then be
  111.                     either x.yyyEz, xx.yyEz or xxx.yEz
  112.                 IntlPRE:    Prefix mode. Like IntlENG, but the
  113.                     power of 10, will be displayed using
  114.                     scientific prefixes (y, z, a, f, p,
  115.                     n, u, m, k, M, G, T, P, E, Z or Y) if
  116.                     within that range. Otherwise identical
  117.                     to IntlSCI.
  118.         nWidth:        The width of the field to contain the number.
  119.         nDecilals:  The numbers of decimals to show, or IntlDEFAULT
  120.                 to use the settings in in WIN.INI.
  121. Returns:    lpString
  122. Remarks:        IntlSTD, IntlFIX, IntlSCI, IntlENG and IntlPRE are defined in
  123.         intl.h
  124.  
  125. IntlCurrencyToString
  126. -------------------
  127. Syntax:     LPSTR FAR PASCAL IntlCurrencyToString(LPSTR  lpString,
  128.                               double dVal,
  129.                               int    nMode,
  130.                               size_t nWidth,
  131.                               int    nDecimals)
  132. Description:    This function converts a floating point number to a string
  133.         representing a currency. The conversion can be to any of the
  134.         formats IntlSTD, IntlFIX, IntlSCI, IntlENG or IntlPRE. The
  135.         function is identical to IntlFloatToString with the addition
  136.         of the currency symbols.
  137. Parameters:    lpString:   The string in which the result of the conversion
  138.                 will be stored.
  139.         dVal:        The floating point number to convert.
  140.         nMode:        The mode to convert to. The modes are:
  141.                 IntlSTD:    The standard conversion. Numbers
  142.                     formatted as xxxx.yyyy. There are two
  143.                     exceptions to this. (1) The number is
  144.                     too large to be contained in the
  145.                     field. (2) The value of the number is
  146.                     so small, it'd be converted to 0.000.
  147.                     In both cases the mode becomes
  148.                     IntlSCI.
  149.                 IntlFIX:    Same as IntlSTD, except the number
  150.                     that are small will be displayed as
  151.                     0.000
  152.                 IntlSCI:    Scientific mode. The number will be
  153.                     converted to the x.yyyEz format.
  154.                 IntlENG:    Engineering mode. Like the IntlSCI,
  155.                     but the power of 10 will always be a
  156.                     multiple of 3. The format can then be
  157.                     either x.yyyEz, xx.yyEz or xxx.yEz
  158.                 IntlPRE:    Prefix mode. Like IntlENG, but the
  159.                     power of 10, will be displayed using
  160.                     scientific prefixes (y, z, a, f, p,
  161.                     n, u, m, k, M, G, T, P, E, Z, Y) if
  162.                     within that range. Otherwise identical
  163.                     to IntlSCI.
  164.         nWidth:        The width of the field to contain the number.
  165.         nDecimals:  The numbers of decimals to show, or    IntlDEFAULT
  166.                 to use the settings in WIN.INI.
  167. Returns:    lpString
  168. Remarks:        IntlSTD, IntlFIX, IntlSCI, IntlENG and IntlPRE are defined in
  169.         intl.h
  170.  
  171.  
  172. IntlStringToDate
  173. ----------------
  174. Syntax:     BOOL FAR PASCAL IntlStringToDate(LPSTR lpString,
  175.                          LPINT lpnYear,
  176.                          LPINT lpnMon,
  177.                          LPINT lpnMday,
  178.                          LPSTR FAR *lpszEnd)
  179. Description:    This functions converts a string containing a date in short
  180.         form, to year, month and day of month. The conversion is
  181.         quite liberal. Either of short and long form of the year
  182.         is allowed. Leading zeroes are ignored.
  183. Parameters:    lpString:    Contains the string to parse.
  184.         lpnYear:    A pointer to an int where the year
  185.                 (formatted as in struct tm) will be
  186.                 stored. It can also be a NULL pointer.
  187.         lpnMon:     A pointer to an int where the month
  188.                 (formatted as in struct tm) will be
  189.                 stored. It can also be a null pointer.
  190.         lpnMday:    A pointer to an int where the day of
  191.                 month (formatted as in struct tm) will
  192.                 be stored. It can also be a null pointer.
  193.         lpszEnd:    A pointer to a char pointer. It will
  194.                 point to the location in lpString where
  195.                 the conversion ended, either upon
  196.                 completion or because of errors. You can
  197.                 also send a NULL pointer.
  198.  
  199. Returns:        Report of the success of the conversion.
  200. Return value:    TRUE:  The conversion was successful.
  201.         FALSE: The conversion failed.
  202. Comment:    There is no check if the date is valid or not.
  203. Remark:     The type LPINT is defined as a pointer to an int, in intl.h
  204.  
  205. IntlStringToTime
  206. ----------------
  207. Syntax:     BOOL FAR PASCAL IntlStringToTime(LPSTR lpString,
  208.                          LPINT lpnHour,
  209.                          LPINT lpnMin,
  210.                          LPINT lpnSec,
  211.                          LPSTR FAR *lpszEnd)
  212.  
  213. Description:    This function converts a time, stored in a string, to
  214.         hours, minutes and seconds. The conversion is quite
  215.         liberal. If the am/pm equivalence is omitted, the string
  216.         is interpreted as a 24 hour time. In 24 hour setting, a
  217.         trailing am/pm equivalence is ignored. Leading zeroes are
  218.         ignored.
  219. Parameters:    lpString:    The string containing the time.
  220.         lpnHour:    A pointer to an int where the
  221.                 hour (formatted as in struct tm)
  222.                 will be stored. It can also be a
  223.                 NULL pointer.
  224.         lpnMin:     A pointer to an int where the
  225.                 minute (formatted as in struct tm)
  226.                 will be stored. It can also be a
  227.                 NULL pointer.
  228.         lpnSec:     A pointer to an int where the
  229.                 seconds (formatted as in struct tm)
  230.                 will be stored. It can also be a
  231.                 NULL pointer.
  232.         lpszEnd:    A pointer to a char pointer. It will
  233.                 point to the location in lpString where
  234.                 the conversion ended, either upon
  235.                 completion or because of errors. You
  236.                 can also send a NULL pointer.
  237.  
  238. Returns:        Report of the success of the conversion.
  239. Return value:   TRUE:   The conversion was successful.
  240.         FALSE:  The conversion failed
  241. Comment:    There is no check if the time is valid or not.
  242. Remark:         The type LPINT is defined as a pointer to an int, in intl.h
  243.  
  244. IntlStringToFloat
  245. -----------------
  246. Syntax:     double FAR PASCAL IntlStringToFloat(LPSTR lpString,
  247.                             LPSTR FAR *lpszEnd)
  248. Description:    This function converts string representation of a floating
  249.         point number to a double. The format of the string can be
  250.         any of the IntlSTD, IntlFIX, IntlSCI, IntlENG or IntlPRE.
  251.  
  252. Parameters:    lpString:    The string containing the number to convert.
  253.         lpszEnd:    A pointer to a char pointer. It will point
  254.                 to the location in lpString where the
  255.                 conversion ended, either upun completion or
  256.                 because of errors. You can also send a NULL
  257.                 pointer.
  258. Returns:    The number or zero if the conversion failed.
  259. Comment:        The number can be in any of the IntlFIX, IntlSTD, IntlSCI,
  260.         IntlENG or the IntlPRE format.
  261.  
  262.  
  263. IntlGetPhrase
  264. -------------
  265. Syntax:     LPSTR FAR PASCAL IntlGetPhrase(LPSTR lpReturn,
  266.                            int   nWidth,
  267.                            LPSTR lpIniFile,
  268.                            LPSTR lpPhrase)
  269. Description:    This function looks up the phrase szPhrase in the current
  270.         language section of the application specific ini file,
  271.         specified in szIniFile, and if not found there, in INTL.INI,
  272.         which contains the phrases listed in appendix  E of the
  273.         CUA. It the phrase is not found in neither the application
  274.         specific ini file, nor INTL.INI, szPhrase will be copied
  275.         into szReturn. The search is case insensitive. If the
  276.         first letter if the lookup-phrase is a capital letter, the
  277.         first letter of the returned string is capitalized.
  278.  
  279. Parameters:    lpReturn:    Points to the buffer that will contain the
  280.                 returned string.
  281.         nWidth:     The size of szReturn.
  282.         lpIniFile:    String containing the name of the
  283.                 application specific ini file. If it's
  284.                 either NULL or points to en empty string,
  285.                 only INTL.INI will be searched for the
  286.                 phrase.
  287.         lpPhrase:    Points to the null terminated phrase.
  288.  
  289. Returns:    The pointer to lpReturn.
  290. Comment:    White space and punctuation characters, according to isspace() 
  291.         and ispunct(), in the beginning and the end of the phrase
  292.         should be omitted in the ini files. They will be automatically
  293.         inserted/appended to the translated phrase.
  294.  
  295. Example:
  296.         Code example:
  297.  
  298.         IntlGetPhrase((LPSTR)szPhrase,
  299.                   sizeof szPhrase,
  300.                   "myini.ini",
  301.                   "** yellow submarine **");
  302.         .
  303.         .
  304.  
  305.         MYINI.INI example:
  306.  
  307.         [ger]
  308.         yellow submarine=gelbes U-Boot
  309.  
  310.         [swe]
  311.         yellow submarine=gul ubåt
  312.  
  313. IntlGetMessage
  314. --------------
  315. Syntax:     LPSTR FAR PASCAL IntlGetMessage(LPSTR lpReturn,
  316.                         int   nWidth,
  317.                         LPSTR lpIniFile,
  318.                         LPSTR lpIdent)
  319. Description:    This function fetches a message, in the current language,
  320.         defined in your application specific ini file. If the
  321.         message is not found in the current language section, the
  322.         [usa] section will be searched. The message identified by
  323.         szIdent MUST be defined in the [usa] section of your
  324.         application specific ini file.
  325.  
  326. Parameters:    lpReturn:    Points to the buffer that will contain
  327.                 the returned string.
  328.         nWidth:     The length of lpReturn.
  329.         lpIniFile:    String containing the name of the
  330.                 application specific ini file.
  331.         lpIdent:    Points to the null terminated identifier
  332.                 string of the message.
  333. Returns:    The pointer to lpReturn.
  334. Comment:        The message can contain the following escape sequences:
  335.         \a      Alert
  336.         \b      Backspace
  337.         \f      Formfeed
  338.         \n      Newline
  339.         \r      Carriage return
  340.         \t      tab
  341.         \v      Vertical tab
  342.         \'      Single quote
  343.         \"      Double quote
  344.         \\      Backslash
  345.  
  346. Example:
  347.         Code example:
  348.  
  349.         IntlGetMessage((LPSTR)szMess,
  350.                 sizeof szMess,
  351.                 "myini.ini",
  352.                 "Demotext");
  353.         .
  354.         .
  355.  
  356.         MYINI.INI example:
  357.  
  358.         [usa]
  359.         Demotext=a few words.
  360.  
  361.         [swe]
  362.         Demotext=några få ord.
  363.  
  364.         [ger]
  365.         Demotext=Ein par Wörter.
  366.