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 / browser / readme.txt < prev    next >
Encoding:
Text File  |  1996-10-15  |  10.4 KB  |  243 lines
  1.  
  2. Sample: container browser
  3. =========================
  4.  
  5. This program implements a browser for SMS objects, it illustrates
  6. possible uses of the following SMS APIs:
  7.     SmsEnumContainers
  8.     SmsEnumFilters
  9.     SmsDataSourceConnect
  10.     SmsDataSourceDisconnect
  11.     SmsOpenContainer
  12.     SmsPopulate
  13.     SmsCloseContainer
  14.     SmsGetNextFolder
  15.     SmsCloseFolder
  16.     SmsRewind
  17.     SmsGetFolderID
  18.     SmsGetFolderType
  19.     SmsGetScalarCount
  20.     SmsGetFolderCount
  21.     SmsEnumFolderTypes
  22.     SmsGetNextScalar
  23.     SmsCreateFilter
  24.     SmsAddToken
  25.     SmsGetAllFilters.
  26.     SmsGetFilterType
  27.     SmsGetToken
  28.     SmsGetTokenCount
  29.     SmsCloseFilter
  30.  
  31. Using the EnumContainers and EnumFilters APIs the program discovers
  32. what containers and filters have been registered with the API engine.
  33. The resulting strings are used to populate the containers and
  34. filters listboxes.
  35.  
  36. After establishing a connection to the appropriate datasource, the user
  37. selects a container to examine. When the "Done" button, in the select
  38. container section of the dialogue, is pressed the "Select" and "Done"
  39. buttons in the Filters section are enabled. At this point the user
  40. should select and configure filters (explanations further down).
  41. Multiple filters may be selected for the container. Pressing the "Done"
  42. button in this section enables the "View container" button at the
  43. lower part of the dialogue.
  44.  
  45. The "View container" button brings up the "The container" dialogue.
  46. This dialogue displays the container type (eg "Package container"), the
  47. number of folders contained in the container, and a list of these
  48. folders. The user then selects a folder and views it ("View folder"
  49. button). The "Done" button dismisses this dialogue and returns to the
  50. main doalogue. In this case all the user can do is terminate the
  51. browser, or restart by pressing the "Connect" button.
  52.  
  53. Viewing folders:
  54. View a folder from the container display brings up a dialogue titled
  55. "View of folder: <the folder's name>". This dialogue has two sections,
  56. folder details, and a sub-folders listbox. The folder details section
  57. displays the folder's ID, type, count of scalars in the folder, count
  58. of sub-folders in the folder, and the number of sub-folder types that
  59. the folder can contain. Refer to the smsapi.h header file, or supplied
  60. help file, for the precise meaning and use of sub-folder type count.
  61. If there are any scalars in the folder the "View scalars" button will
  62. be enabled. Pressing this brings up a dialogue displaying the scalars and
  63. and their values.
  64. The sub-folder list displays the names of any sub-folders. Again, if
  65. there are any sub-folders the "View sub-folder" button will be enabled.
  66. Pressing this will cause the dialogue contents to be replaced with the
  67. details of the selected folder.
  68.  
  69. Configuring filters:
  70. There are currently 8 filters available:
  71.     site, machine, group, job, architecure, package, attribute, and
  72.         sitelimit.
  73. After selecting a filter the user must configure it in order for it to
  74. be applied to the container, this is done in the "Configure filter"
  75. dialogue.
  76. Filters are composed of one or more tokens, the dialogue allows the
  77. setting of tokens into the specified filter.
  78. There are, currently, two forms of APIs for inserting tokens into
  79. filters, Add{And|Or}Token3 and Add{And|Or}Token4. The former version is
  80. used by all filters with the exception of Machine filters.
  81. If the dialogue detects that it is processing a Machine filter, then an
  82. additional edit control is enabled. For all other filters it is disabled.
  83. Machine filters need to be able to specify a group class, an attribute
  84. name, an operator, and a value. Other filters do not need the group
  85. class field.
  86. The usage of the three common fields differs considerably among filters,
  87. indeed, some filters do not even need all three parameters to be filled
  88. in.
  89.  
  90.     Site filter
  91.     -----------
  92. Possible values for the name field are: RootSite, and SiteByCode.
  93. They inform the container what site folders it should contain.
  94. If no site filter is applied then the site container will contain
  95. one folder for each site in the datasource.
  96. If RootSite is specified, then no other parameters are needed, and the
  97. container will only contain a folder for the root site.
  98. If SiteByCode is specified, then the Value field must contain the three
  99. letter site code for the requested site. Mixing of a RootSite with
  100. SiteByCode tokens makes no sense. (You have asked for only the root site
  101. and then additional sites.) In this case the RootSite token will take
  102. precedence and the other tokens will be discarded.
  103. It is possible, and perfectly sensible, to set multiple SiteByCode
  104. tokens. In this case the container will be populated with one folder for
  105. each of the requested sites. However, in this case the tokens must be
  106. ORed into the filter. To say that you want the boolean product of site
  107. ABC and site DEF makes no sense since no site can possibly have to
  108. site codes.
  109.  
  110.  
  111.     Group filter
  112.     -----------
  113. This filter allows you to select the groupclasses that will be included
  114. for any machines that you wish to browse. As such it is only relevant
  115. for a container that includes machines within its hierarchy, eg site
  116. container, machine container.
  117. Configure this filter as follows:
  118.  
  119. Name field: must say "GroupClass"
  120. GroupClass field: a valid groupclass name such as
  121.         "MICROSOFT|IDENTIFICATION|1.0".
  122. Operator combobox: select the "is" operator. It's the only one allowed.
  123.  
  124. It is possible to OR multiple tokens together. For instance, selecting
  125. (OR) a token for MICROSOFT|IDENTIFICATION|1.0 group, select (OR) a
  126. token for MICROSOFT|NETCARD|1.0 group. When viewing the parent machine
  127. folder there will be two sub-folders, one for each of these groups.
  128. Note: some groupclasses have multiple instances, eg MICROSOFT|ENVIRONMENT|1.0.
  129. In this case there will be as many machine group sub-folders as there
  130. are instances of this group.
  131. As in site filters, ANDing tokens together makes no sense.
  132.  
  133.  
  134.     Job filter
  135.     -----------
  136. Three options exist for filtering jobs: by job ID, by job type, and
  137. by job status. In all three cases the name and value fields are used.
  138. The operation field, currently, is not.
  139. To set tokens, enter one of the strings "JobType", "JobID", or "JobStatus"
  140. in the name field.
  141. For JobType tokens the value should be one of the following (again as
  142. a literal string):
  143.     "Install"           - for workstation install jobs.
  144.     "Server"            - for server share jobs.
  145.     "Remove package"    - for remove package jobs.
  146.     "System"            - for NAD transfer, site, and minijobs.
  147.  
  148. For retrieving jobs by their ID, you should type "JobID" in the name
  149. field, and the (eight character) job name in the value field.
  150.  
  151. For retrieving jobs by their status, type "JobStatus" in the name field.
  152. The value field should contain one of the following string values:
  153.     "Pending"
  154.     "Active"
  155.     "Cancelled"
  156.     "Complete"
  157.     "Failed"
  158.     "Active failed"
  159.  
  160. Job tokens can be combined together inside a filter. For instance, the
  161. tokens: JobType = Install OR JobID = "ABC00123" will result in the
  162. retrieval of all workstation install jobs, and the job with the name
  163. "ABC00123".
  164.  
  165.  
  166.     Architecture filter
  167.     -------------------
  168. This uses one parameter, the value field. Additional documentation
  169. will describe what values are allowed. For instance, "Personal Computer"
  170. will result in machines of the Personal Computer architectures being
  171. selected. "SMSEvent" will result in SMS event MIFs being selected.
  172.  
  173.  
  174.     Package filter
  175.     --------------
  176. Currently, there is only one type of token for package filters, this
  177. is the Type token. The type field should say "PackageType". The value field
  178. is one of the following literal strings:
  179.     "Workstation"
  180.     "Server"
  181.     "Inventory"
  182. These can be combined by ORing them into a filter, in which case
  183. you could retrieve, say, Workstation and Sharing packages.
  184. If no package filter is applied, then the system defaults to returning
  185. all packages that are in the datasource.
  186.  
  187.  
  188.     Attribute filter
  189.     ----------------
  190. An attribute filter acts in the same way as an SMS query format. It
  191. is used when enumerating/selecting machines and defines what machine
  192. attributes should be accepted by the container. This has a significant
  193. performance gain over using group filters.
  194. For instance, if the user only wants to see the Name, SMSLocation,
  195. and NetCardID from a machine's Identification group, then an
  196. attribute filter containing tokens for each of these attributes will
  197. result in a much faster folder selection than specifying a group
  198. filter for then Identification group. Additionally, only the information
  199. requested will be returned.
  200.  
  201. The name field should contain the groupclass (eg MICROSOFT|IDENTIFICATION|1.0).
  202. The value field should contain the name of the attribute (eg "Name").
  203. The operator is not currently used.
  204.  
  205. NOTE: attribute filters specifying attributes that exist in multiple
  206. instance groups (eg the Environment group) will produce indeterminate
  207. results. They should not be used in this case.
  208.  
  209.  
  210.         Machine filter
  211.         --------------
  212. A machine filter is the API equivalent of an SMS query. To configure this
  213. type of filter you must provide the following:
  214.  
  215. Architecture field: this must contain an architecture that is known to
  216.     SMS, exam,ples are: "Personal Computer", "SMSEvent", "UserGroups".
  217.     Consult the SMS documentation for full details about architectures.
  218.     GroupClass field: a valid groupclass name such as
  219.         "MICROSOFT|IDENTIFICATION|1.0".
  220. Attribute name field: the name of an attribute that exists within the
  221.     specified groupclass. For example "SystemRole".
  222. Value: the value for the attribute.
  223. Operator combobox: this is a dropdown listbox that contains operators that
  224.     define the relationship between the attribute and the value.
  225.     For example, "SystemRole" "is" "Server". In this case "is" denotes the
  226.     string equality operator.
  227.  
  228. This filter can be applied to site, machine, and machine group containers.
  229.  
  230. For more details refer to your SMS documentation on SMS queries.
  231.  
  232.  
  233.         Sitelimit filter
  234.         ----------------
  235. This filter can only be applied to a machine container. Using it you
  236. can specify that you only want machines from a specific site and,
  237. optionally, a specified domain to be included within the container.
  238. Configure this filter as follows:
  239.  
  240. Site code field: the three letter site code
  241. [optional] Domain: the name of the domain
  242.  
  243.