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