workbench/libs/identify/idexpansion.c

   1 /*
   2  * Copyright (c) 2010-2011 Matthias Rustler
   3  *
   4  * Permission is hereby granted, free of charge, to any person obtaining a
   5  * copy of this software and associated documentation files (the "Software"),
   6  * to deal in the Software without restriction, including without limitation
   7  * the rights to use, copy, modify, merge, publish, distribute, sublicense,
   8  * and/or sell copies of the Software, and to permit persons to whom the
   9  * Software is furnished to do so, subject to the following conditions:
  10  *
  11  * The above copyright notice and this permission notice shall be included
  12  * in all copies or substantial portions of the Software.
  13  *
  14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
  15  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
  17  * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  18  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  19  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  20  * IN THE SOFTWARE.
  21  *
  22  * $Id$
  23  */
  24
  25 #include <proto/utility.h>
  26 #include <clib/alib_protos.h>
  27
  28 #include <string.h>
  29
  30 #include "identify_intern.h"
  31 #include "identify.h"
  32
  33 /*****************************************************************************
  34
  35     NAME */
  36 #include <proto/identify.h>
  37
  38         AROS_LH1(LONG, IdExpansion,
  39
  40 /*  SYNOPSIS */
  41         AROS_LHA(struct TagItem *, taglist, A0),
  42
  43 /*  LOCATION */
  44         struct IdentifyBaseIntern *, IdentifyBase, 5, Identify)
  45
  46 /*  FUNCTION
  47         Gets the name and class of the expansion and it's manufacturer.
  48
  49     INPUTS
  50         TagList -- (struct TagItem *) tags that describe further options.
  51
  52     RESULT
  53         Error   -- (LONG) error code, or 0 if everything went fine.
  54
  55                    IDERR_NOLENGTH  -- IDTAG_StrLength has been set to 0!
  56                    IDERR_BADID     -- IDTAG_ManufID and IDTAG_ProdID were
  57                                       out of range or one of them was missing.
  58                    IDERR_DONE      -- Checked all expansions using the
  59                                       IDTAG_Expansion tag. This is not really an error.
  60                    IDERR_SECONDARY -- This expansion is secondary to a primary
  61                                       expansion entry.
  62
  63     TAGS
  64         IDTAG_ConfigDev -- (struct ConfigDev *) ConfigDev structure
  65                            containing all information. You should use this tag if ever
  66                            possible, since there are more possibilities to recognize and
  67                            distinguish between a board.
  68
  69         IDTAG_ManufID   -- (UWORD) Manufacturer ID if ConfigDev is not
  70                            provided. You must also provide IDTAG_ProdID!
  71
  72         IDTAG_ProdID    -- (UBYTE) Product ID if ConfigDev is not
  73                            provided. You must also provide IDTAG_ManufID!
  74
  75         IDTAG_ManufStr  -- (STRPTR) Pointer to a buffer space for the
  76                            manufacturer name. You may skip this tag if you do not want
  77                            to get this string.
  78
  79         IDTAG_ProdStr   -- (STRPTR) Pointer to a buffer space for the
  80                            product name. You may skip this tag if you do not want
  81                            to get this string.
  82
  83         IDTAG_ClassStr  -- (STRPTR) Pointer to a buffer space for the
  84                            product class. You may skip this tag if you do not want to get
  85                            this string.
  86
  87         IDTAG_StrLength -- (UWORD) Buffer length, including
  88                            termination. Defaults to 50.
  89
  90         IDTAG_Expansion -- [V6] (struct ConfigDev **) Use this tag to
  91                            easily traverse through the expansion board list. Init the
  92                            pointed variable with NULL. After each call, you will find
  93                            the current ConfigDev pointer in this variable. If you are
  94                            done, this function returns IDERR_DONE and the variable is set
  95                            to NULL. See example.
  96
  97         IDTAG_Secondary -- [V7] (BOOL) If set to TRUE, identify will
  98                            warn about secondary expansions. E.g. some graphic boards
  99                            create more than one entry in the expansion list. Then, one
 100                            entry is the primary entry, and any additional are secondary.
 101                            This tag does only make sense when checking all mounted
 102                            expansions. Defaults to FALSE. (See Bugs)
 103
 104         IDTAG_ClassID   -- [V8] (ULONG *) The ULONG field will be filled
 105                            with a numerical class ID of the expansion (see include file:
 106                            IDCID_...). IMPORTANT: You MUST be prepared to get a number
 107                            that does not match to any IDCID value. In this case, assume
 108                            IDCID_MISC.
 109
 110         IDTAG_Localize  -- [V8] (BOOL) FALSE to get English strings
 111                            only, TRUE for localized strings. This is useful for applications
 112                            with English as only language. Defaults to TRUE.
 113
 114     EXAMPLE
 115         To check all expansion boards, you may use this code:
 116
 117         void PrintExpansions(void)
 118         {
 119           struct ConfigDev *expans = NULL;
 120           char manuf[IDENTIFYBUFLEN];
 121           char prod[IDENTIFYBUFLEN];
 122           char pclass[IDENTIFYBUFLEN];
 123
 124           while(!IdExpansionTags(
 125                   IDTAG_ManufStr ,manuf,
 126                   IDTAG_ProdStr  ,prod,
 127                   IDTAG_ClassStr ,pclass,
 128                   IDTAG_Expansion,&expans,
 129                   TAG_DONE))
 130           {
 131             Printf("Current ConfigDev = 0x%08lx\n",expans);
 132             Printf("  Manufacturer    = %s\n",manuf);
 133             Printf("  Product         = %s\n",prod);
 134             Printf("  Expansion class = %s\n\n",class);
 135           }
 136         }
 137
 138     NOTES
 139         This function isn't implemented yet.
 140
 141         If the manufacturer or the product is not known, the string will be
 142         filled with its number.
 143
 144         This call is guaranteed to preserve all registers except D0.
 145
 146     BUGS
 147         You must also provide IDTAG_ProdStr if you want to use IDTAG_Secondary.
 148
 149     SEE ALSO
 150
 151     INTERNALS
 152
 153     HISTORY
 154
 155
 156 *****************************************************************************/
 157 {
 158     AROS_LIBFUNC_INIT
 159
 160     STRPTR manufstr = NULL;
 161     STRPTR prodstr = NULL;
 162     STRPTR classstr = NULL;
 163     ULONG strlength = 50;
 164     struct ConfigDev **expansion = NULL;
 165     BOOL secondary = FALSE;
 166     ULONG *classid = NULL;
 167     BOOL localize = TRUE;
 168
 169     struct TagItem *tag;
 170     struct TagItem *tags;
 171
 172     for (tags = taglist; (tag = NextTagItem(&tags)); )
 173     {
 174         switch (tag->ti_Tag)
 175         {
 176             case IDTAG_ConfigDev:
 177                 // doesn't return anything
 178                 break;
 179
 180             case IDTAG_ManufID:
 181                 // doesn't return anything
 182                 break;
 183
 184             case IDTAG_ProdID:
 185                 // doesn't return anything
 186                 break;
 187
 188             case IDTAG_ManufStr:
 189                 manufstr = (STRPTR)tag->ti_Data;
 190                 break;
 191
 192             case IDTAG_ProdStr:
 193                 prodstr = (STRPTR)tag->ti_Data;
 194                 break;
 195
 196             case IDTAG_ClassStr:
 197                 classstr = (STRPTR)tag->ti_Data;
 198                 break;
 199
 200             case IDTAG_StrLength:
 201                 strlength = tag->ti_Data;
 202                 break;
 203
 204             case IDTAG_Expansion:
 205                 expansion = (struct ConfigDev **)tag->ti_Data;
 206                 break;
 207
 208             case IDTAG_Secondary:
 209                 secondary = tag->ti_Data ? TRUE : FALSE;
 210                 break;
 211
 212             case IDTAG_ClassID:
 213                 classid = (ULONG *)tag->ti_Data;
 214                 break;
 215
 216             case IDTAG_Localize:
 217                 localize = tag->ti_Data ? TRUE : FALSE;
 218                 break;
 219
 220         }
 221     }
 222
 223     if (strlength <=0)
 224     {
 225         return IDERR_NOLENGTH;
 226     }
 227
 228     if (localize) {
 229         /* FIXME: Do we need to do something here? */
 230     }
 231
 232     if (secondary) {
 233         /* FIXME: Do we need to do something here? */
 234     }
 235
 236     // return something to avoid crashes when function is called
 237     if (manufstr)
 238     {
 239         strlcpy(manufstr, "Unknown", strlength);
 240     }
 241     if (prodstr)
 242     {
 243         strlcpy(prodstr, "Unknown", strlength);
 244     }
 245     if (classstr)
 246     {
 247         strlcpy(classstr, "Unknown", strlength);
 248     }
 249     if (expansion)
 250     {
 251         *expansion = NULL;
 252     }
 253     if (classid)
 254     {
 255         *classid = IDCID_UNKNOWN;
 256     }
 257
 258     return 0;
 259
 260     AROS_LIBFUNC_EXIT
 261 } /* IdExpansion */