home *** CD-ROM | disk | FTP | other *** search
/ Mac OS 9 Serial Number Archive / SN Archive 2023.11.04.toast / BSNG / SDK / BSNG SDK 2.5 / BSNG API.h next >
Encoding:
C/C++ Source or Header  |  1998-03-11  |  16.7 KB  |  282 lines  |  [TEXT/CWIE]
  1. /*
  2.  * $Workfile:: BSNG API.h                                                     $
  3.  * $Revision:: 4                                                              $
  4.  *
  5.  * $Author:: Buck Rogers                                                      $
  6.  * $Modtime:: 11.03.1998 04:20 Uhr                                            $
  7.  *
  8.  * $History:: BSNG API.h                                                      $
  9.  * 
  10.  * *****************  Version 4  *****************
  11.  * User: Buck Rogers  Date: 11.03.1998   Time: 04:21 Uhr
  12.  * Updated in $/BSNG/Plugins/BSNG SDK
  13.  * added new controls like popup menus, checkboxes and radio buttons to the
  14.  * API
  15.  * 
  16.  * *****************  Version 3  *****************
  17.  * User: Buck Rogers  Date: 29.10.1997   Time: 16:01 Uhr
  18.  * Updated in $/BSNG/Plugins/BSNG SDK
  19.  * added errorText to display custom error messages
  20.  * 
  21.  * *****************  Version 2  *****************
  22.  * User: Buck Rogers  Date: 05.10.1997   Time: 19:12 Uhr
  23.  * Updated in $/BSNG/Plugins/BSNG SDK
  24.  * Added name, company and number of copies items that contain the default
  25.  * values set in the BSNG App preferences
  26.  * 
  27.  * *****************  Version 1  *****************
  28.  * User: Buck Rogers  Date: 30.09.1997   Time: 18:31 Uhr
  29.  * Created in $/BSNG/Plugins/BSNG SDK
  30.  * Adding subproject 'BSNG' to '$/'
  31.  *
  32.  * $NoKeywords::                                                              $
  33.  */
  34.  
  35.  
  36. #pragma once
  37.  
  38.  
  39. #if PRAGMA_ALIGN_SUPPORTED
  40. #pragma options align=mac68k
  41. #endif
  42.  
  43. /*
  44.     These are the IDs of the dialog/panel items you can use.
  45.     MAKE SURE THAT EVERY ITEM YOU ADD TO YOUR LAYOUT IS WITHIN THAT RANGE AND SENDS MESSAGE VALUES INSIDE THAT RANGE!!!
  46.     
  47.     Note:    The only items that need special ID and/or message ranges are:
  48.             LGAEditFields (ID range: between kEditItem1 = 100001 and kEditItem10 = 100010)
  49.             LPopupButtons (ID and message range: between kPopupItem1 = 200001 and kPopupItem10 = 200010)
  50.             LGAPushButtons (ID and message range: between 300000 and 399999)
  51.             LCheckboxes (ID and message range: between kCheckboxItem1 = 400001 and kCheckboxItem10 = 400010)
  52.             LRadioButtons (ID and message range: between kRadioItem1 = 500001 and kRadioItem10 = 500010)
  53.     
  54.     Everything else you add, like LGACaptions or LGAFocusBorders should have an ID smaller than 100000 though to
  55.     avoid possible conflicts with the BSNG App in the future.
  56.     
  57.     ADDITIONAL NOTE!!! (read for even more fun)
  58.         I tested the following control elements: 
  59.         (for all other controls you might want to test you still have to use the appropiate IDs and value messages for each control.
  60.         That means if you want to use LGAPopups instead of LPopupButtons you still have to use the IDs/messages I mentioned
  61.         above - kPopupItem1...kPopupItem10)
  62.         
  63.         LGAEditField    for TextEdit fields (NO OTHER WILL WORK!!!, sorry)
  64.         LPopupButton    for popup menus (other similar controls like LGAPopup or LBevelButton might work
  65.         LGAPushButtons    for "normal" buttons (other similar controls like LGATextButton or LGAIconButton in button mode might work)
  66.         LCheckboxes        for checkboxes (other similar controls like LGACheckBox or LGAIconButton in switch mode might work)
  67.         LRadioButton    for radio buttons (other similar controls like LGARadioButton or LGAIconButton in radio button mode might work)
  68.         
  69.         If you use other controls than those I tested you'll know if they work as soon as you try out your plugin. If the BSNG App quits
  70.         or freezes when you select your plugin one or more of the controls you use don't work. If you click on the controls and
  71.         nothing happens the control either doesn't work or you set the wrong control IDs/value messages for that control.
  72.         
  73.         Nevertheless, I hope you'll have lots of fun with these new additions!!!
  74. */
  75.  
  76. enum EditFieldItem        {kEditItem1 = 100001, kEditItem2 = 100002, kEditItem3 = 100003, kEditItem4 = 100004, kEditItem5 = 100005,
  77.                          kEditItem6 = 100006, kEditItem7 = 100007, kEditItem8 = 100008, kEditItem9 = 100009, kEditItem10 = 100010};    
  78.  
  79. enum PopupMenuItem        {kPopupItem1 = 200001, kPopupItem2 = 200002, kPopupItem3 = 200003, kPopupItem4 = 200004, kPopupItem5 = 200005,
  80.                          kPopupItem6 = 200006, kPopupItem7 = 200007, kPopupItem8 = 200008, kPopupItem9 = 200009, kPopupItem10 = 200010};    
  81.  
  82. enum CheckboxItem        {kCheckboxItem1 = 400001, kCheckboxItem2 = 400002, kCheckboxItem3 = 400003, kCheckboxItem4 = 400004, kCheckboxItem5 = 400005,
  83.                          kCheckboxItem6 = 400006, kCheckboxItem7 = 400007, kCheckboxItem8 = 400008, kCheckboxItem9 = 400009, kCheckboxItem10 = 400010};    
  84.  
  85. enum RadioItem            {kRadioItem1 = 500001, kRadioItem2 = 500002, kRadioItem3 = 500003, kRadioItem4 = 500004, kRadioItem5 = 500005,
  86.                          kRadioItem6 = 500006, kRadioItem7 = 500007, kRadioItem8 = 500008, kRadioItem9 = 500009, kRadioItem10 = 500010};    
  87.  
  88. /*
  89.     These are constants you can use to access the itemValue array. If you want to access the value the user entered in your
  90.     LGAEditField with the ID kEditItem2 you can use itemValue[1] or for more readability itemValue[kItemValue2]
  91. */
  92.  
  93. enum EditFieldValue        {kItemValue1 = 0, kItemValue2 = 1, kItemValue3 = 2, kItemValue4 = 3, kItemValue5 = 4,
  94.                          kItemValue6 = 5, kItemValue7 = 6, kItemValue8 = 7, kItemValue9 = 8, kItemValue10 = 9};
  95.  
  96.  
  97. /*
  98.     These are constants you can use to access the selectedPopupItem array. If you want to access the menu item the user selected in your
  99.     LPopupButton with the ID kPopupItem3 you can use selectedPopupItem[2] or for more readability selectedPopupItem[kPopupMenu3]
  100. */
  101.  
  102. enum PopupMenu            {kPopupMenu1 = 0, kPopupMenu2 = 1, kPopupMenu3 = 2, kPopupMenu4 = 3, kPopupMenu5 = 4,
  103.                          kPopupMenu6 = 5, kPopupMenu7 = 6, kPopupMenu8 = 7, kPopupMenu9 = 8, kPopupMenu10 = 9};
  104.  
  105.  
  106. /*
  107.     These are constants you can use to access the checkboxSelected array. If you want to know if the user selected/checked your
  108.     LCheckbox with the ID kCheckboxItem5 you can use checkboxSelected[4] or for more readability checkboxSelected[kCheckbox5]
  109. */
  110.  
  111. enum Checkbox            {kCheckbox1 = 0, kCheckbox2 = 1, kCheckbox3 = 2, kCheckbox4 = 3, kCheckbox5 = 4,
  112.                          kCheckbox6 = 5, kCheckbox7 = 6, kCheckbox8 = 7, kCheckbox9 = 8, kCheckbox10 = 9};
  113.  
  114.  
  115. /*
  116.     These are constants you can use to access the radioSelected array. If you want to know if the user selected/checked your
  117.     LRadioButton with the ID kRadioItem9 you can use radioSelected[8] or for more readability radioSelected[kRadioButton9]
  118.     
  119.     Note:    if you correctly create radio button groups in Constructor the BSNG App will take care of correct radio button
  120.             behaviour (if you select another radio button than the currently selected one in the radio group the button
  121.             belongs to all other radio buttons of that group will automatically be disabled). If you don't define radio button
  122.             groups you have to simulate that behaviour manually in the 'DoItemHit' function of your plugin by setting the
  123.             correct values in the radioSelected array whenever a radio button gets hit/pressed.
  124. */
  125.  
  126. enum RadioButton        {kRadioButton1 = 0, kRadioButton2 = 1, kRadioButton3 = 2, kRadioButton4 = 3, kRadioButton5 = 4,
  127.                          kRadioButton6 = 5, kRadioButton7 = 6, kRadioButton8 = 7, kRadioButton9 = 8, kRadioButton10 = 9};
  128.  
  129.  
  130. /*
  131.     Here are the descriptions of all the possible messages your plugin can recieve:
  132.  
  133.     msgExtInit                 Will be passed when your plugin gets loaded.
  134.                             This is the time to set the 'wantsRandomButton' and 'canAddToSNList' values and to initialize your
  135.                             global variables. You should also load all additional resources (if you use any in your plug) that
  136.                             are needed for your calculations, like CRC tables etc., at this point of time.
  137.                             If your initialisation failed for some reason report that back to the BSNG App by setting 'error'
  138.                             to errExtInitFailed, if your init was successful set 'error' to errExtNoErr
  139.     
  140.     msgExtCalcHit            Will be passed when the user pressed the 'Calculate' button in the BSNG App.
  141.                             You should validate all necessary data for your calculations (passed to you in the 'itemValue' array)
  142.                             before you start calculating. set 'error' to errExtIncorrectValue with the corresponding
  143.                             EditFieldItem in 'errorInItem' back to the BSNG App if the validation failed.
  144.                             If the validation was succesful start your calculation and pass the result back in the appropiate entry
  145.                             in the 'itemValue' array (e.g. use itemValue[kItemValue2] if your output LGAEditField has the ID kEditItem2,
  146.                             use itemValue[kItemValue3] if your output LGAEditField has the ID kEditItem3 etc).
  147.     
  148.     msgExtRandomHit            You will only receive that message if you set 'wantsRandomButton' to true at Init time.
  149.                             Create a random serial number not dependent on user input and fill in all the necessary data into the
  150.                             'itemValue' array to display your calculations (see msgExtCalcHit how to do that)
  151.     
  152.     msgExtItemHit            You will receive that message only when you added one or more LPopupButtons, LGAPushButtons, LCheckboxes
  153.                             and/or LRadioButtons to your layout.
  154.                             The IDs and control messages have to be in the range listed above to make this work. The message
  155.                             of the control that was pressed will be passed to you in 'itemMessage'.
  156.                             You can do lots of things with this feature, like display your own about box, play a sound or whatever
  157.                             else comes to your mind. Actually this is very powerful because you get all control you need to
  158.                             'customize' your plugin, but please keep in mind not to 'bloat' your plugin by adding too much fancy stuff.
  159.                             All the values you probably changed for some reason in the 'itemValue' array or one of the other value arrays
  160.                             will be displayed to the user when the BSNG App gets control again. Have fun :-)
  161.                             
  162.     
  163.     msgExtCreateRandom        Your plugin will only get this message if you set 'canAddToSNList' to true at Init time.
  164.                             Use the 'outputRefNum' to write your randomly calculated serial numbers to the filestream.
  165.                             Use FSWrite and/or the helper functions myOutputPStr, myOutputSuffixedPStr, myOutputText
  166.                             and myOutputSuffixedText from "standard utils" (included with this package) to write to the filestream.
  167.                             You should calculate 'numOfListNumbers' random numbers if you can and write them to the stream...
  168.                                 
  169.     msgExtCleanup            Will be passed when your plugin gets unloaded.
  170.                             All memory allocations you made at Init time or whenever and all the resources you loaded should be
  171.                             deallocated/freed/dissposed when your plugin receives this message to avoid memory leaks.
  172. */ 
  173.  
  174.  
  175. enum ExternalMessage    {msgExtInit = 1, msgExtCalcHit = 2, msgExtRandomHit = 3, msgExtItemHit = 4, msgExtCreateRandom = 5, msgExtCleanup = 6};
  176.  
  177. /*
  178.     Here are the descriptions of all supported errors at the moment. If you pass another value back to the BSNG App than those
  179.     listed here the user will be prompted with an 'the plugin reported an unknown error, please continue with caution' alert
  180.     
  181.     errExtInitFailed        Your plugin failed to initialize itself at Init time
  182.     
  183.     errExtIncorrectValue    report that error at msgExtCalcHit time if the user entered an incorrect value into one of the LGAEditField.
  184.                             Report the field containing the error back to the BSNG App by setting 'errorInItem' to the
  185.                             corresponding LGAEditField ID (kEditItem1...kEditItem10)
  186.     
  187.     errExtWritingToList        report that error when you got the msgExtCreateRandom message and for one or the other reason can't
  188.                             write your data to the list. If you report that error the creation of the complete list will be aborted.
  189.     
  190.     errExtNoErr                report this if everything works fine :-)
  191. */
  192.  
  193. enum ExternalError        {errExtInitFailed = -100000, errExtIncorrectValue = -100001, errExtWritingToList = -100002, errExtNoErr = 0};
  194.  
  195.  
  196. typedef struct
  197. {
  198.     short                theMessage;                /*    set by the BSNG App, you have to react to these messages */
  199.                                                 /*    (see ExternalMessage above) */
  200.     
  201.     unsigned long        itemMessage;            /*    if you added one or more LPopupButtons, LGAPushButtons, LCheckboxes and/or */
  202.                                                 /*    LRadioButtons to your layout you'll find the message you configured for that */
  203.                                                 /*    control in here when it got pressed/selected. The control IDs and messages MUST */
  204.                                                 /*    be within the ranges mentioned above to make it work */
  205.     
  206.     Boolean                wantsRandomButton;        /*    set to true at Init time if your plugin can create random serial numbers */
  207.     
  208.     Boolean                canAddToSNList;            /*    set to true at Init time if your plugin can create numbers for the */
  209.                                                 /*    Random Serial Number List */
  210.     
  211.     Str63                name;                    /*    name, company and numCopies are default values entered in the BSNG App preferences. */
  212.     Str63                company;                /*    if possible copy these in values in the corresponding itemValue items at Init time */
  213.     Str15                numCopies;                /*    so that these values can appear as default in your generator. Also make sure that */
  214.                                                 /*    you make a serial number using these infos when the Serial Number List gets */
  215.                                                 /*    created (of course only if your plugin is a name-based algorithm) */
  216.     
  217.     unsigned short        numOfListNumbers;        /*    how many numbers to create for the random Serial Number List */
  218.     
  219.     short                outputRefNum;            /*    the reference number of the file to write to when we build the */
  220.                                                 /*    random Serial Number List */
  221.     
  222.     long                error;                    /*    if an error occured put the appropiate error number (see 'ExternalError' above) */
  223.                                                 /*    in here. You can create your own custom errors by setting this to a positive, */
  224.                                                 /*    non-zero value and putting your error text into the 'errorText' variable */
  225.                                                 
  226.     unsigned long        errorInItem;            /*    if the error that occured is of type 'errExtIncorrectValue' put the
  227.                                                 /*    appropiate 'EditFieldItem' in here. Lets say the wrong value is in itemValue[3] */
  228.                                                 /*    which is equal to itemValue[kItemValue4] put kEditItem4 into this field */
  229.     
  230.     unsigned long        randSeed1;                /*    set by the BSNG App, you can use these two randSeed values to initialize the */
  231.     unsigned long        randSeed2;                /*    Ultra Random Number Generator (source included) or any other Random Number Gen */
  232.     
  233.     unsigned long        appLaunchTime;            /*    set by the BSNG App, the time the BSNG App was launched in Ticks */
  234.     DateTimeRec            appLaunchDate;            /*    set by the BSNG App, the time the BSNG App was launched in a DateTimeRec */
  235.     
  236.     StringPtr            itemValue[10];            /*    You can add up to 10 LGAEditFields to your layout. The IDs of your LGAEditField */
  237.                                                 /*    MUST be between 100001 and 100010 (kEditItem1...kEditItem10). */
  238.     
  239.     Str255                errorText;                /*    Whenever you signal an error in the 'error' variable you can make the BSNG app */
  240.                                                 /*    to display your own error text. Just put the string you want to show into this */
  241.                                                 /*    variable and the BSNG app will display it in an Alert. Your error text can be */
  242.                                                 /*    max. 255 characters long and has to be a pascal string. If you leave this string */
  243.                                                 /*    empty the BSNG app will display its own error alert as before. */
  244.                                                 /*    You can now also create your own error conditions, whenever you encounter an */
  245.                                                 /*    error other than those predefined set the 'error' variable to a positive, */
  246.                                                 /*    non-zero value and put the text you want to display into this variable */
  247.                                                 /*    Thanks to Mididman for suggesting this errorText variable */
  248.     
  249.     long                selectedPopupItem[10];    /*    You can add up to 10 LPopupButtons to your layout. The IDs and value messages of */
  250.                                                 /*    your LPopupButtons MUST be between 200001 and 200010 (kPopupItem1...kPopupItem10). */
  251.                                                 /*    The currently selected menu item of every popup is stored in this array */
  252.     
  253.     Boolean                checkboxSelected[10];    /*    You can add up to 10 LCheckboxes to your layout. The IDs and value messages of */
  254.                                                 /*    your LCheckboxes MUST be between 400001 and 400010 (kCheckboxItem1... */
  255.                                                 /*    kCheckboxItem10). The current status of every checkbox (unchecked = false, */
  256.                                                 /*    checked = true) is stored in this array */
  257.     
  258.     Boolean                radioSelected[10];        /*    You can add up to 10 LRadioButtons to your layout. The IDs and value messages of */
  259.                                                 /*    your LRadioButtons MUST be between 500001 and 500010 (kRadioItem1...kRadioItem10). */
  260.                                                 /*    The current status of every radio button (unselected = false, selected = true) */
  261.                                                 /*    is stored in this array */
  262.     
  263. } BSNGParamBlock, *BSNGParamBlockPtr;
  264.  
  265.  
  266. /*
  267.     IMPORTANT!!! more additional notes:
  268.     
  269.     You MUST create the following resouces, otherwise your plugin will not work:
  270.     
  271.     'cicn' ID 1000    must contain the icon displayed in the plugin list in the BSNG App
  272.     'STR ' ID 1000    must contain the text displayed under the icon, the max. supported length of this text is 27 characters
  273.     'PPob' ID 1000    must contain the layout displayed on the right side of the serial number generator window when your plugin
  274.                     gets selected. Use Metrowerks Constructor 2.4.4a1 or better (included in this distribution) to customize this view.
  275.                     
  276.                     YOU CAN'T USE/CONSTRUCT THE NEW FEATURES LIKE POPUPS AND CHECKBOXES CORRECTLY WITH EARLIER VERSIONS OF CONTRUCTOR!!!
  277. */
  278.  
  279. #if PRAGMA_ALIGN_SUPPORTED
  280. #pragma options align=reset
  281. #endif
  282.