Source code of Windows XP (NT5)
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

827 lines
22 KiB

  1. /*
  2. * token.h
  3. *
  4. * Copyright (c) 1993 - 1995 by DataBeam Corporation, Lexington, KY
  5. *
  6. * Abstract:
  7. * This is the interface file for the Token class. Objects of this class
  8. * represent tokens in the MCS environment. Whenever a token is allocated
  9. * by a user, one of these objects is created. Its job is to handle all
  10. * requests that are specific to the token ID with which it is associated.
  11. *
  12. * Tokens in the MCS environment are used for critical resource management.
  13. * The exact use of tokens is up to the user applications attaching to
  14. * MCS. They are provided as a generic resource.
  15. *
  16. * Tokens can be "owned" by one or more users. There are two types of
  17. * ownership. There is exclusive ownership, where only one user can
  18. * own the token at a time. That user has "grabbed" the token. And there
  19. * is non-exclusive ownership, where several users can own the token at
  20. * the same time. Those users have "inhibited" the token. It is not
  21. * possible to mix exclusive and non-exclusive ownership.
  22. *
  23. * If a user has grabbed a token, that same user can inhibit the token,
  24. * thus converting to non-exclusive ownership. Similarly, if a user is
  25. * the sole inhibitor of a token, that user can grab the token, thus
  26. * converting to exclusive ownership.
  27. *
  28. * During a domain merge operation, it is necessary to merge tokens upward
  29. * to the new Top Provider of the enlarged domain. This class also defines
  30. * a member function allowing it to be told to issue a merge request with
  31. * all of its state contained therein.
  32. *
  33. * Caveats:
  34. * None.
  35. *
  36. * Author:
  37. * James P. Galvin, Jr.
  38. */
  39. #ifndef _TOKEN_
  40. #define _TOKEN_
  41. /*
  42. * This is the class definition for the Token class.
  43. */
  44. class Token
  45. {
  46. public:
  47. Token (
  48. TokenID token_id,
  49. PDomain local_provider,
  50. PConnection top_provider,
  51. CChannelList2 *channel_list,
  52. CAttachmentList *attachment_list);
  53. Token (
  54. TokenID token_id,
  55. PDomain local_provider,
  56. PConnection top_provider,
  57. CChannelList2 *channel_list,
  58. CAttachmentList *attachment_list,
  59. TokenState token_state,
  60. UserID grabber,
  61. CUidList *inhibitor_list,
  62. UserID recipient);
  63. ~Token ();
  64. void SetTopProvider(PConnection top_provider) { m_pConnToTopProvider = top_provider; }
  65. BOOL IsTopProvider(void) { return (m_pConnToTopProvider == NULL); }
  66. TokenState GetTokenState () { return (Token_State); };
  67. BOOL IsValid ();
  68. Void IssueMergeRequest ();
  69. Void TokenGrabRequest (
  70. CAttachment *originator,
  71. UserID uidInitiator,
  72. TokenID token_id);
  73. Void TokenGrabConfirm (
  74. Result result,
  75. UserID uidInitiator,
  76. TokenID token_id,
  77. TokenStatus token_status);
  78. Void TokenInhibitRequest (
  79. CAttachment *originator,
  80. UserID uidInitiator,
  81. TokenID token_id);
  82. Void TokenInhibitConfirm (
  83. Result result,
  84. UserID uidInitiator,
  85. TokenID token_id,
  86. TokenStatus token_status);
  87. Void TokenGiveRequest (
  88. CAttachment *originator,
  89. PTokenGiveRecord pTokenGiveRec);
  90. Void TokenGiveIndication (
  91. PTokenGiveRecord pTokenGiveRec);
  92. Void TokenGiveResponse (
  93. Result result,
  94. UserID receiver_id,
  95. TokenID token_id);
  96. Void TokenGiveConfirm (
  97. Result result,
  98. UserID uidInitiator,
  99. TokenID token_id,
  100. TokenStatus token_status);
  101. Void TokenPleaseRequest (
  102. UserID uidInitiator,
  103. TokenID token_id);
  104. Void TokenPleaseIndication (
  105. UserID uidInitiator,
  106. TokenID token_id);
  107. Void TokenReleaseRequest (
  108. CAttachment *originator,
  109. UserID uidInitiator,
  110. TokenID token_id);
  111. Void TokenReleaseConfirm (
  112. Result result,
  113. UserID uidInitiator,
  114. TokenID token_id,
  115. TokenStatus token_status);
  116. Void TokenTestRequest (
  117. CAttachment *originator,
  118. UserID uidInitiator,
  119. TokenID token_id);
  120. Void TokenTestConfirm (
  121. UserID uidInitiator,
  122. TokenID token_id,
  123. TokenStatus token_status);
  124. private:
  125. BOOL ValidateUserID (
  126. UserID user_id);
  127. CAttachment *GetUserAttachment (
  128. UserID user_id);
  129. Void IssueTokenReleaseIndication (
  130. UserID user_id);
  131. Void BuildAttachmentList (
  132. CUidList *user_id_list,
  133. CAttachmentList *attachment_list);
  134. TokenID Token_ID;
  135. PDomain m_pDomain;
  136. PConnection m_pConnToTopProvider;
  137. CChannelList2 *m_pChannelList2;
  138. CAttachmentList *m_pAttachmentList;
  139. TokenState Token_State;
  140. UserID m_uidGrabber;
  141. CUidList m_InhibitorList;
  142. UserID m_uidRecipient;
  143. };
  144. /*
  145. * Token (
  146. * TokenID token_id,
  147. * PDomain local_provider,
  148. * PConnection top_provider,
  149. * PChannelList channel_list,
  150. * PAttachmentList attachment_list)
  151. *
  152. * Functional Description:
  153. * This is the constructor for the Token class. It simply initializes
  154. * local instance variables with the passed in values. It also marks
  155. * the state of the token as available.
  156. *
  157. * Formal Parameters:
  158. * token_id (i)
  159. * This is the token ID that this token object is associated with.
  160. * local_provider (i)
  161. * This is a pointer to the local provider. A Token object will
  162. * never actually send a command to the local provider, but it needs
  163. * this value to use a parameter when it sends commands to various
  164. * attachments (since it is doing so on behalf of the local provider).
  165. * top_provider (i)
  166. * This is a pointer to the top provider. This is used by the
  167. * Token object when it needs to issue a request to the Top
  168. * Provider.
  169. * channel_list (i)
  170. * This is a pointer to the domain's channel list, which identifies
  171. * all valid channels in the domain. This is used by token objects
  172. * to validate user IDs.
  173. * attachment_list (i)
  174. * This is a pointer to the domain's attachment list, which identifies
  175. * all valid attachments in the domain. This is used by token
  176. * objects to validate joined attachments.
  177. *
  178. * Return Value:
  179. * None.
  180. *
  181. * Side Effects:
  182. * None.
  183. *
  184. * Caveats:
  185. * None.
  186. */
  187. /*
  188. * Token (
  189. * TokenID token_id,
  190. * PDomain local_provider,
  191. * PConnection top_provider,
  192. * PChannelList channel_list,
  193. * PAttachmentList attachment_list,
  194. * TokenState token_state,
  195. * UserID grabber,
  196. * CUidList *inhibitor_list,
  197. * UserID recipient)
  198. *
  199. * Functional Description:
  200. * This is the constructor for the Token class. It simply initializes
  201. * local instance variables with the passed in values. It also marks
  202. * the state of the token as available.
  203. *
  204. * Formal Parameters:
  205. * token_id (i)
  206. * This is the token ID that this token object is associated with.
  207. * local_provider (i)
  208. * This is a pointer to the local provider. A Token object will
  209. * never actually send a command to the local provider, but it needs
  210. * this value to use a parameter when it sends commands to various
  211. * attachments (since it is doing so on behalf of the local provider).
  212. * top_provider (i)
  213. * This is a pointer to the top provider. This is used by the
  214. * Token object when it needs to issue a request to the Top
  215. * Provider.
  216. * channel_list (i)
  217. * This is a pointer to the domain's channel list, which identifies
  218. * all valid channels in the domain. This is used by token objects
  219. * to validate user IDs.
  220. * attachment_list (i)
  221. * This is a pointer to the domain's attachment list, which identifies
  222. * all valid attachments in the domain. This is used by token
  223. * objects to validate joined attachments.
  224. * token_state (i)
  225. * This is the state of the token being merged.
  226. * grabber (i)
  227. * This is the user ID of the user who has the token grabbed (this is
  228. * only valid if the token state is grabbed or giving).
  229. * inhibitor_list (i)
  230. * This is a list of the users who have the token inhibited (this is
  231. * only valid if the token state is inhibited).
  232. * recipient (i)
  233. * This is the user ID of the user who is being offered the token
  234. * as part of a give operation (this is only valid if the token state
  235. * is giving or given).
  236. *
  237. * Return Value:
  238. * None.
  239. *
  240. * Side Effects:
  241. * None.
  242. *
  243. * Caveats:
  244. * None.
  245. */
  246. /*
  247. * ~Token ()
  248. *
  249. * Functional Description:
  250. * This is a virtual destructor defined for the Token class. It does
  251. * nothing at this time.
  252. *
  253. * Formal Parameters:
  254. * None.
  255. *
  256. * Return Value:
  257. * None.
  258. *
  259. * Side Effects:
  260. * None.
  261. *
  262. * Caveats:
  263. * None.
  264. */
  265. /*
  266. * Void SetTopProvider (
  267. * PConnection top_provider)
  268. *
  269. * Functional Description:
  270. * This member function is used to change the identity of the Top Provider
  271. * in an existing token. The only time this will really occur is when
  272. * a provider that used to be the Top Provider merges into another
  273. * domain, and therefore ceases to be the Top Provider. When the merge
  274. * operation has been successfully completed, this function allows the
  275. * domain to inform all of its Token objects about the identity of
  276. * the new Top Provider.
  277. *
  278. * Formal Parameters:
  279. * top_provider (i)
  280. * This is a pointer to the new Top Provider.
  281. *
  282. * Return Value:
  283. * None.
  284. *
  285. * Side Effects:
  286. * None.
  287. *
  288. * Caveats:
  289. * None.
  290. */
  291. /*
  292. * TokenState GetTokenState ()
  293. *
  294. * Functional Description:
  295. * This function returns the current state of the token. This is used
  296. * by the caller primarily during a merge operation, when decisions have
  297. * to made about what tokens can and cannot be merged.
  298. *
  299. * Formal Parameters:
  300. * None.
  301. *
  302. * Return Value:
  303. * TOKEN_AVAILABLE if the token is not in use.
  304. * TOKEN_GRABBED if the token is currently grabbed.
  305. * TOKEN_INHIBITED if the token is currently inhiited.
  306. * TOKEN_GIVING if the token is currently in the giving state.
  307. * TOKEN_GIVEN if the token is currently in the given state.
  308. *
  309. * Side Effects:
  310. * None.
  311. *
  312. * Caveats:
  313. * None.
  314. */
  315. /*
  316. * BOOL IsValid ()
  317. *
  318. * Functional Description:
  319. * This function returns TRUE if the token is still valid, or FALSE if the
  320. * token needs to be deleted. A token is valid if it has ANY owners
  321. * (grabbers, inhibitors, or recipient).
  322. *
  323. * Formal Parameters:
  324. * None.
  325. *
  326. * Return Value:
  327. * TRUE if the token is valid.
  328. * FALSE if the token needs to be deleted.
  329. *
  330. * Side Effects:
  331. * None.
  332. *
  333. * Caveats:
  334. * None.
  335. */
  336. /*
  337. * Void IssueMergeRequest ()
  338. *
  339. * Functional Description:
  340. * This function is called during a domain merge operation. It causes
  341. * the token object to pack it state and send it out in a merge token
  342. * request to the top provider.
  343. *
  344. * Formal Parameters:
  345. * None.
  346. *
  347. * Return Value:
  348. * None.
  349. *
  350. * Side Effects:
  351. * None.
  352. *
  353. * Caveats:
  354. * None.
  355. */
  356. /*
  357. * Void TokenGrabRequest (
  358. * PCommandTarget originator,
  359. * UserID uidInitiator,
  360. * TokenID token_id)
  361. *
  362. * Functional Description:
  363. * This function is called when a user wishes to grab a token. Depending
  364. * on the current state of the token, the request will either succeed or
  365. * fail. Either way, an appropriate token grab confirm will be issued
  366. * to the requesting user.
  367. *
  368. * Formal Parameters:
  369. * originator (i)
  370. * This is a pointer to the attachment that leads to the originator
  371. * of the request.
  372. * uidInitiator (i)
  373. * This is the user ID of the user that originated the request.
  374. * token_id (i)
  375. * This is the token being acted upon.
  376. *
  377. * Return Value:
  378. * None.
  379. *
  380. * Side Effects:
  381. * None.
  382. *
  383. * Caveats:
  384. * None.
  385. */
  386. /*
  387. * Void TokenGrabConfirm (
  388. * PCommandTarget originator,
  389. * Result result,
  390. * UserID uidInitiator,
  391. * TokenID token_id,
  392. * TokenStatus token_status)
  393. *
  394. * Functional Description:
  395. * This function is called as a result of the top provider answering a
  396. * previous grab request. It tells the user whether or not the request
  397. * succeeded.
  398. *
  399. * Formal Parameters:
  400. * originator (i)
  401. * This is a pointer to the attachment that leads to the originator
  402. * of the request.
  403. * result (i)
  404. * This is the result of the request. RESULT_SUCCESSFUL indicates
  405. * that the token was successfully grabbed.
  406. * uidInitiator (i)
  407. * This is the user ID of the user that originated the request.
  408. * token_id (i)
  409. * This is the token being acted upon.
  410. * token_status (i)
  411. * This is the status of the token after this request is processed.
  412. *
  413. * Return Value:
  414. * None.
  415. *
  416. * Side Effects:
  417. * None.
  418. *
  419. * Caveats:
  420. * None.
  421. */
  422. /*
  423. * Void TokenInhibitRequest (
  424. * PCommandTarget originator,
  425. * UserID uidInitiator,
  426. * TokenID token_id)
  427. *
  428. * Functional Description:
  429. * This function is called when a user wishes to inhibit a token.
  430. * Depending on the current state of the token, the request will either
  431. * succeed or fail. Either way, an appropriate token inhibit confirm will
  432. * be issued to the requesting user.
  433. *
  434. * Formal Parameters:
  435. * originator (i)
  436. * This is a pointer to the attachment that leads to the originator
  437. * of the request.
  438. * uidInitiator (i)
  439. * This is the user ID of the user that originated the request.
  440. * token_id (i)
  441. * This is the token being acted upon.
  442. *
  443. * Return Value:
  444. * None.
  445. *
  446. * Side Effects:
  447. * None.
  448. *
  449. * Caveats:
  450. * None.
  451. */
  452. /*
  453. * Void TokenInhibitConfirm (
  454. * PCommandTarget originator,
  455. * Result result,
  456. * UserID uidInitiator,
  457. * TokenID token_id,
  458. * TokenStatus token_status)
  459. *
  460. * Functional Description:
  461. * This function is called as a result of the top provider answering a
  462. * previous inhibit request. It tells the user whether or not the request
  463. * succeeded.
  464. *
  465. * Formal Parameters:
  466. * originator (i)
  467. * This is a pointer to the attachment that leads to the originator
  468. * of the request.
  469. * result (i)
  470. * This is the result of the request. RESULT_SUCCESSFUL indicates
  471. * that the token was successfully inhibited.
  472. * uidInitiator (i)
  473. * This is the user ID of the user that originated the request.
  474. * token_id (i)
  475. * This is the token being acted upon.
  476. * token_status (i)
  477. * This is the status of the token after this request is processed.
  478. *
  479. * Return Value:
  480. * None.
  481. *
  482. * Side Effects:
  483. * None.
  484. *
  485. * Caveats:
  486. * None.
  487. */
  488. /*
  489. * Void TokenGiveRequest (
  490. * PCommandTarget originator,
  491. * PTokenGiveRecord pTokenGiveRec)
  492. *
  493. * Functional Description:
  494. * This function is called when a user wishes to give a token to another
  495. * user. Depending on the current state of the token, the request will
  496. * either succeed or fail. Either way, an appropriate token grab confirm
  497. * will be issued to the requesting user.
  498. *
  499. * Formal Parameters:
  500. * originator (i)
  501. * This is a pointer to the attachment that leads to the originator
  502. * of the request.
  503. * pTokenGiveRec (i)
  504. * This is the address of a structure containing the following information:
  505. * The ID of the user attempting to give away the token.
  506. * The ID of the token being given.
  507. * The ID of the user that the token is being given to.
  508. *
  509. * Return Value:
  510. * None.
  511. *
  512. * Side Effects:
  513. * None.
  514. *
  515. * Caveats:
  516. * None.
  517. */
  518. /*
  519. * Void TokenGiveIndication (
  520. * PCommandTarget originator,
  521. * PTokenGiveRecord pTokenGiveRec)
  522. *
  523. * Functional Description:
  524. * This function is called when the top provider wants to indicate to a
  525. * user that another user is offering them a token.
  526. *
  527. * Formal Parameters:
  528. * originator (i)
  529. * This is a pointer to the attachment that leads to the originator
  530. * of the request.
  531. * pTokenGiveRec (i)
  532. * This is the address of a structure containing the following information:
  533. * The ID of the user attempting to give away the token.
  534. * The ID of the token being given.
  535. * The ID of the user that the token is being given to.
  536. *
  537. * Return Value:
  538. * None.
  539. *
  540. * Side Effects:
  541. * None.
  542. *
  543. * Caveats:
  544. * None.
  545. */
  546. /*
  547. * Void TokenGiveResponse (
  548. * PCommandTarget originator,
  549. * Result result,
  550. * UserID receiver_id,
  551. * TokenID token_id)
  552. *
  553. * Functional Description:
  554. * This function is called in response to a previous give indication. It
  555. * contains the user's answer as to whether or not the token was
  556. * accepted.
  557. *
  558. * Formal Parameters:
  559. * originator (i)
  560. * This is a pointer to the attachment that leads to the originator
  561. * of the request.
  562. * result (i)
  563. * This is the result of the request. RESULT_SUCCESSFUL indicates that
  564. * the recipient has accepted the token.
  565. * token_id (i)
  566. * This is the token being acted upon.
  567. * receiver_id (i)
  568. * This is the ID of the user that is to receive the token.
  569. *
  570. * Return Value:
  571. * None.
  572. *
  573. * Side Effects:
  574. * None.
  575. *
  576. * Caveats:
  577. * None.
  578. */
  579. /*
  580. * Void TokenGiveConfirm (
  581. * PCommandTarget originator,
  582. * Result result,
  583. * UserID uidInitiator,
  584. * TokenID token_id,
  585. * TokenStatus token_status)
  586. *
  587. * Functional Description:
  588. * This function is called to send a confirmation back to a user who
  589. * is trying to give away a token. It lets the user know whether or
  590. * not the operation was successful.
  591. *
  592. * Formal Parameters:
  593. * originator (i)
  594. * This is a pointer to the attachment that leads to the originator
  595. * of the request.
  596. * result (i)
  597. * This is the result of the request. RESULT_SUCCESSFUL indicates that
  598. * the recipient has accepted the token.
  599. * uidInitiator (i)
  600. * This is the user ID of the user that originated the request.
  601. * token_id (i)
  602. * This is the token being acted upon.
  603. * token_status (i)
  604. * This is the status of the token after the operation.
  605. *
  606. * Return Value:
  607. * None.
  608. *
  609. * Side Effects:
  610. * None.
  611. *
  612. * Caveats:
  613. * None.
  614. */
  615. /*
  616. * Void TokenPleaseRequest (
  617. * PCommandTarget originator,
  618. * UserID uidInitiator,
  619. * TokenID token_id)
  620. *
  621. * Functional Description:
  622. * This function is called when a user wishes to ask the current owners
  623. * of a token to relinquish it.
  624. *
  625. * Formal Parameters:
  626. * originator (i)
  627. * This is a pointer to the attachment that leads to the originator
  628. * of the request.
  629. * uidInitiator (i)
  630. * This is the user ID of the user that originated the request.
  631. * token_id (i)
  632. * This is the token being acted upon.
  633. *
  634. * Return Value:
  635. * None.
  636. *
  637. * Side Effects:
  638. * None.
  639. *
  640. * Caveats:
  641. * None.
  642. */
  643. /*
  644. * Void TokenPleaseIndication (
  645. * PCommandTarget originator,
  646. * UserID uidInitiator,
  647. * TokenID token_id)
  648. *
  649. * Functional Description:
  650. * This function is initially called by the top provider in response to
  651. * a received token please request. It is forwarded to all users who
  652. * currently own the specified token, asking them to relinquish it.
  653. *
  654. * Formal Parameters:
  655. * originator (i)
  656. * This is a pointer to the attachment that leads to the originator
  657. * of the request.
  658. * uidInitiator (i)
  659. * This is the user ID of the user that originated the request.
  660. * token_id (i)
  661. * This is the token being acted upon.
  662. *
  663. * Return Value:
  664. * None.
  665. *
  666. * Side Effects:
  667. * None.
  668. *
  669. * Caveats:
  670. * None.
  671. */
  672. /*
  673. * BOOL TokenReleaseRequest (
  674. * PCommandTarget originator,
  675. * UserID uidInitiator,
  676. * TokenID token_id)
  677. *
  678. * Functional Description:
  679. * This function is called when a user wishes to release a token.
  680. * Depending on the current state of the token, the request will either
  681. * succeed or fail. Either way, an appropriate token release confirm will
  682. * be issued to the requesting user.
  683. *
  684. * Formal Parameters:
  685. * originator (i)
  686. * This is a pointer to the attachment that leads to the originator
  687. * of the request.
  688. * uidInitiator (i)
  689. * This is the user ID of the user that originated the request.
  690. * token_id (i)
  691. * This is the token being acted upon.
  692. *
  693. * Return Value:
  694. * None.
  695. *
  696. * Side Effects:
  697. * None.
  698. *
  699. * Caveats:
  700. * None.
  701. */
  702. /*
  703. * Void TokenReleaseConfirm (
  704. * PCommandTarget originator,
  705. * Result result,
  706. * UserID uidInitiator,
  707. * TokenID token_id,
  708. * TokenStatus token_status)
  709. *
  710. * Functional Description:
  711. * This function is called as a result of the top provider answering a
  712. * previous release request. It tells the user whether or not the request
  713. * succeeded.
  714. *
  715. * Formal Parameters:
  716. * originator (i)
  717. * This is a pointer to the attachment that leads to the originator
  718. * of the request.
  719. * result (i)
  720. * This is the result of the request. RESULT_SUCCESSFUL indicates
  721. * that the token was successfully released.
  722. * uidInitiator (i)
  723. * This is the user ID of the user that originated the request.
  724. * token_id (i)
  725. * This is the token being acted upon.
  726. * token_status (i)
  727. * This is the status of the token after this request is processed.
  728. *
  729. * Return Value:
  730. * None.
  731. *
  732. * Side Effects:
  733. * None.
  734. *
  735. * Caveats:
  736. * None.
  737. */
  738. /*
  739. * Void TokenTestRequest (
  740. * PCommandTarget originator,
  741. * UserID uidInitiator,
  742. * TokenID token_id)
  743. *
  744. * Functional Description:
  745. * This function is called when a user wishes to test the current state
  746. * of a token. The token will issue a token test confirm to the
  747. * originating user containing the requested information.
  748. *
  749. * Formal Parameters:
  750. * originator (i)
  751. * This is a pointer to the attachment that leads to the originator
  752. * of the request.
  753. * uidInitiator (i)
  754. * This is the user ID of the user that originated the request.
  755. * token_id (i)
  756. * This is the token being acted upon.
  757. *
  758. * Return Value:
  759. * None.
  760. *
  761. * Side Effects:
  762. * None.
  763. *
  764. * Caveats:
  765. * None.
  766. */
  767. /*
  768. * Void TokenTestConfirm (
  769. * PCommandTarget originator,
  770. * UserID uidInitiator,
  771. * TokenID token_id,
  772. * TokenStatus token_status)
  773. *
  774. * Functional Description:
  775. * This function is called as a result of the top provider answering a
  776. * previous test request. It tells the user the current state of the
  777. * token.
  778. *
  779. * Formal Parameters:
  780. * originator (i)
  781. * This is a pointer to the attachment that leads to the originator
  782. * of the request.
  783. * uidInitiator (i)
  784. * This is the user ID of the user that originated the request.
  785. * token_id (i)
  786. * This is the token being tested.
  787. * token_status (i)
  788. * This is the current status of the token.
  789. *
  790. * Return Value:
  791. * None.
  792. *
  793. * Side Effects:
  794. * None.
  795. *
  796. * Caveats:
  797. * None.
  798. */
  799. #endif