home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Windows Gam…ming Gurus (2nd Edition) / Disc2.iso / msdn_vcb / samples / vc98 / sdk / sysmgmt / sms / smsapi / enumobj / readme.txt < prev   
Text File  |  1996-10-15  |  4KB  |  96 lines
  1.     SMS API Example: object enumeration. (enumobj.exe)
  2.     ==================================================
  3.  
  4. This sample illustrates the use of the SMS object enumeration APIs.
  5. The objects involved here are currently Architectures and Platforms,
  6. and their descendent objects.
  7.  
  8. The API draws a distinction between 'first-class' and 'secondary objects.
  9. A 'first-class' object is one that can be described by SMS without any
  10. prior knowledge. The first-class objects that are known to the system
  11. is returned by calling SmsEnumObjectTypes. Calling this will currently
  12. result in two object-types being returned: Architectures and Platforms.
  13. In order to determine what Architectures exist the user then calls
  14. SmsEnumObjects, passing "Architectures" as the types of object that we
  15. are interested in. What is returned from this call depends on the
  16. individual database. The set of architectures will certainly include:
  17.         Personal Computer
  18.         SMSEvents
  19.         SNMP Traps      (SMS 1.2 and above)
  20.         PackageLocation
  21.         UserGroups
  22.         etc.
  23. These are all secondary objects whose type is "Architecture".
  24.  
  25. It is now possible to determine what objects each of these contain.
  26. For instance, every object of type 'Architecture' will contain one or
  27. more object of type 'Group', such as "MICROSOFT|IDENTIFICATION|1.0".
  28. Note that it is impossible to determine what groups exist without first
  29. knowing what architecture the user is interested in. Similarly, while a
  30. Group object contains Attribute objects, it is impossible to know what
  31. Attributes exist without knowing what group we are talking about.
  32. This is why the SmsEnumObjects API has the notion of a predecessor list.
  33.  
  34. The data type used by the API to describe an object that it returns
  35. is known as OBJDESCRIPTOR. Looking at the definition for this data type
  36. (see smsapi.h) we see that there are the following fields:
  37.         
  38.     DWORD objType                Type of this object.
  39.  
  40.     SMSBUFF szName               Object name (eg 'Personal Computer')
  41.  
  42.     SMSBUFF szFriendlyName       Friendly name. Only used in groups
  43.                                  where szName would be, eg,
  44.                                  'MICROSOFT|IDENTIFICATION|1.0', the
  45.                                  friendly name would be 'Identification'.
  46.  
  47.     BOOL bGotFriendlyName        TRUE if we have a friendly name.
  48.  
  49.     DWORD dwRelopMin             For attributes, indicates range of
  50.     DWORD dwRelopMax             relational operators that can be used
  51.                                  for this attribute.
  52.  
  53.     BOOL bGotRelops              TRUE if we have the relops fields set.
  54.  
  55.  
  56. The 'objType' parameter is one of the set of OT_ defines (also in smsapi.h).
  57. This tells the user what type of object is described by this OBJDESCRIPTOR.
  58.  
  59. 'szName' provides the name for this object (eg 'Personal Computer', 'SMSID').
  60.  
  61. 'szFriendlyName' if this is not null then it gives a user-friendly name for
  62. the object (see above). This is only used in the case of Group objects, but
  63. the 'bGotFriendlyName' datum will indicate whether this field is present
  64. or not.
  65.  
  66. 'dwRelopMin' and 'dwRelopMax' are used by attributes. They inform the caller
  67. what the range of operators are for the attribute in question. 'bGotRelops'
  68. is TRUE if these fields are present.
  69. The values of these relational operators is from the file qrycodes.h.
  70.  
  71.  
  72. Note that this example operates in a recursive manner in order to enumerate
  73. all objects that are known to the API set.
  74. A different use would of the APIs would be something like: given a specific
  75. architecture and a specific group, what attributes exist. Code for this would
  76. be something like:
  77.         (where Architecture is Personal Computer, and Group is MICROSOFT|
  78.          VIDEO|1.0)
  79.  
  80.  
  81.     SMSBUFF aPreds[10];
  82.     strcpy( aPreds[0], "Architectures" );
  83.     strcpy( aPreds[1], "MICROSOFT|VIDEO|1.0 );
  84.     strcpy( aPreds[2], "MICROSOFT|VIDEO|1.0 );
  85.  
  86.     SmsEnumObjects( hConnect,   // Handle to datasource connection.
  87.                     pszObj,     // Attribute.
  88.                     pPreds,     // see above.
  89.                     ctPreds,    // 3: Architectures, PC, MS|VIDEO|1.0
  90.                     Objects,    // filled in by API.
  91.                     &ctObjs );  // filled in by API.
  92.  
  93. This would return, in 'Objects', all attributes for the video group.    
  94.  
  95.  
  96.