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 / attribut / readme.txt < prev   
Encoding:
Text File  |  1996-10-15  |  4.1 KB  |  88 lines
  1.     SMS API Example: attribute filters. (attribut.exe)
  2.     ==================================================
  3.  
  4. This sample illustrates the use of the Attribute filter that is
  5. applied to a site container in order to enumerate specified
  6. properties of a machine (architecture: Personal Computer).
  7.  
  8. Applying an attribute filter in order to enumerate machines is
  9. faster than setting group filters and then retrieving specified
  10. machine group scalars (machine properties). This is due to the
  11. nature of the SQL operations that have to be performed.
  12. This filter is also useful in the respect that only the information
  13. that is requested will be returned.
  14.  
  15. This program opens a site container, constructs and applies an
  16. attribute filter composed of three tokens:
  17.     a) Name scalar        (from MICROSOFT|IDENTIFICATION|1.0 group).
  18.     b) SMSLocation scalar (from MICROSOFT|IDENTIFICATION|1.0 group).
  19.     c) NetCardID scalar   (from MICROSOFT|IDENTIFICATION|1.0 group).
  20.  
  21. Two other filters are applied to the container:
  22. 1. Site filter: to instruct the container to retrieve the root site.
  23. 2. Architecture filter: to specify that we want machines of the
  24.    Personal Computer architecture.
  25.  
  26. After populating the container, which will cause the container to
  27. contain only a site folder for the root site, we open the folder
  28. and then close the container.
  29. Closing the container is an important step since the container
  30. increments a use count that is held for all descendant folders. If
  31. the container is not closed as soon as possible we will never be
  32. able to free the resources for any descendant folder. This would
  33. cause us to exceed virtual memory very quickly for a database of
  34. any size.
  35.  
  36. We then enter a loop to deal with any folders contained in the
  37. site container. Although, by definition, there can only be one
  38. folder in the site container, this loop is an example of the
  39. general procedure to be followed in folder enumeration involving
  40. the SMS API set.
  41.  
  42. The function DisplayFolder does most of the work.
  43. It is passed a handle to the folder currently under examination,
  44. at this stage all he is aware of is that this is a handle to a
  45. folder. No mention is made yet as to what type of folder this is.
  46.  
  47. For display purposes we retrieve the ID of the folder. We then
  48. discovers the folder's properties; these are:
  49. 1. the folder's type, and
  50. 2. the number of scalars and sub-folders contained in this folder.
  51.  
  52. The scalars are then displayed.
  53.  
  54. For each folder we will open each of its child sub-folders, storing
  55. the handles away in a temporary list, and then close the folder.
  56. This is identical to what we did above for the container.
  57.  
  58.  
  59. Turning our attention now to the DisplayScalars function we see
  60. that this consists of a simple loop that repeatedly tries to
  61. retrieve a scalar from the folder. The loop terminates when there
  62. are no more scalars in the folder.
  63. Careful note should be taken of the use of the SCALAR structure.
  64. This is composed (currently - expect minor modifications here) of
  65. six fields, two of which are pointers to memory that must be
  66. allocated by the application.
  67. When retrieving a scalar we set the pszName and pszValue pointers
  68. to buffers. The pszName buffer will receive the name of the scalar,
  69. no indication is given by the API as to what size that buffer
  70. should be. However, a size of 256 (see SMS_DATA_BUFF_SIZE define)
  71. is guaranteed to be sufficient.
  72. The pszValue field is used when retrieving string data. For binary
  73. data the pvalue field is used.
  74. Associated with this is a length field. Prior to retrieving a
  75. scalar, you must set the length field to the size of this buffer.
  76. If the scalar is a string or binary, then the actual size of the
  77. data will be returned here. If the buffer was too small then the
  78. return code from the API will be SMS_MORE_DATA.
  79.  
  80. Once this API has been called, we execute a switch statement to
  81. find out what the type of the scalar is. For integer and time
  82. scalars the value will be in the dwValue member of the SCALAR
  83. structure. The time value can be converted to a string by using
  84. one of the standard C library routines, or a CTime object from
  85. MFC.
  86.  
  87.  
  88.