VirtualBox

Changeset 62784 in vbox


Ignore:
Timestamp:
Aug 1, 2016 6:56:19 AM (9 years ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
109371
Message:

VBoxAuth.h: doxygen!

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/include/VBox/VBoxAuth.h

    r62476 r62784  
    2727#define ___VBox_vboxauth_h
    2828
     29/** @defgroup grp_vboxauth VirtualBox External Authentication Library Interface
     30 * @{
     31 */
     32
    2933/* The following 2 enums are 32 bits values.*/
    3034typedef enum AuthResult
    … …  
    4650} AuthGuestJudgement;
    4751
    48 /* UUID memory representation. Array of 16 bytes. */
     52/** UUID memory representation. Array of 16 bytes.
     53 *
     54 * @note VirtualBox uses a consistent binary representation of UUIDs on all platforms. For this reason
     55 * the integer fields comprising the UUID are stored as little endian values. If you want to pass such
     56 * UUIDs to code which assumes that the integer fields are big endian (often also called network byte
     57 * order), you need to adjust the contents of the UUID to e.g. achieve the same string representation.
     58 *
     59 * The required changes are:
     60 *     - reverse the order of byte 0, 1, 2 and 3
     61 *     - reverse the order of byte 4 and 5
     62 *     - reverse the order of byte 6 and 7.
     63 *
     64 * Using this conversion you will get identical results when converting the binary UUID to the string
     65 * representation.
     66 */
    4967typedef unsigned char AUTHUUID[16];
    5068typedef AUTHUUID *PAUTHUUID;
    51 /*
    52 Note: VirtualBox uses a consistent binary representation of UUIDs on all platforms. For this reason
    53 the integer fields comprising the UUID are stored as little endian values. If you want to pass such
    54 UUIDs to code which assumes that the integer fields are big endian (often also called network byte
    55 order), you need to adjust the contents of the UUID to e.g. achieve the same string representation.
    56 The required changes are:
    57  * reverse the order of byte 0, 1, 2 and 3
    58  * reverse the order of byte 4 and 5
    59  * reverse the order of byte 6 and 7.
    60 Using this conversion you will get identical results when converting the binary UUID to the string
    61 representation.
    62 */
    6369
    64 /* The library entry point calling convention. */
     70/** The library entry point calling convention. */
    6571#ifdef _MSC_VER
    6672# define AUTHCALL __cdecl
    … …  
    7581 * Authentication library entry point.
    7682 *
    77  * Parameters:
    78  *
    79  *   pUuid            Pointer to the UUID of the accessed virtual machine. Can be NULL.
    80  *   guestJudgement   Result of the guest authentication.
    81  *   szUser           User name passed in by the client (UTF8).
    82  *   szPassword       Password passed in by the client (UTF8).
    83  *   szDomain         Domain passed in by the client (UTF8).
     83 * @param  pUuid            Pointer to the UUID of the accessed virtual machine. Can be NULL.
     84 * @param  guestJudgement   Result of the guest authentication.
     85 * @param  szUser           User name passed in by the client (UTF8).
     86 * @param  szPassword       Password passed in by the client (UTF8).
     87 * @param  szDomain         Domain passed in by the client (UTF8).
    8488 *
    8589 * Return code:
    8690 *
    87  *   AuthAccessDenied    Client access has been denied.
    88  *   AuthAccessGranted   Client has the right to use the
    89  *                       virtual machine.
    90  *   AuthDelegateToGuest Guest operating system must
    91  *                       authenticate the client and the
    92  *                       library must be called again with
    93  *                       the result of the guest
    94  *                       authentication.
     91 * @retval AuthAccessDenied    Client access has been denied.
     92 * @retval AuthAccessGranted   Client has the right to use the virtual machine.
     93 * @retval AuthDelegateToGuest Guest operating system must
     94 *                              authenticate the client and the
     95 *                              library must be called again with
     96 *                              the result of the guest
     97 *                              authentication.
    9598 */
    96 typedef AuthResult AUTHCALL AUTHENTRY(PAUTHUUID pUuid,
    97                                       AuthGuestJudgement guestJudgement,
    98                                       const char *szUser,
    99                                       const char *szPassword,
    100                                       const char *szDomain);
    101 
    102 
    103 typedef AUTHENTRY *PAUTHENTRY;
    104 
     99typedef AuthResult AUTHCALL FNAUTHENTRY(PAUTHUUID pUuid,
     100                                        AuthGuestJudgement guestJudgement,
     101                                        const char *szUser,
     102                                        const char *szPassword,
     103                                        const char *szDomain);
     104/** Pointer to a FNAUTHENTRY function. */
     105typedef FNAUTHENTRY *PFNAUTHENTRY;
     106/** @deprecated   */
     107typedef FNAUTHENTRY  AUTHENTRY;
     108/** @deprecated   */
     109typedef PFNAUTHENTRY PAUTHENTRY;
     110/** Name of the FNAUTHENTRY entry point. */
    105111#define AUTHENTRY_NAME "VRDPAuth"
    106112
    … …  
    108114 * Authentication library entry point version 2.
    109115 *
    110  * Parameters:
     116 * @param  pUuid            Pointer to the UUID of the accessed virtual machine. Can be NULL.
     117 * @param  guestJudgement   Result of the guest authentication.
     118 * @param  szUser           User name passed in by the client (UTF8).
     119 * @param  szPassword       Password passed in by the client (UTF8).
     120 * @param  szDomain         Domain passed in by the client (UTF8).
     121 * @param  fLogon           Boolean flag. Indicates whether the entry point is
     122 *                          called for a client logon or the client disconnect.
     123 * @param  clientId         Server side unique identifier of the client.
    111124 *
    112  *   pUuid            Pointer to the UUID of the accessed virtual machine. Can be NULL.
    113  *   guestJudgement   Result of the guest authentication.
    114  *   szUser           User name passed in by the client (UTF8).
    115  *   szPassword       Password passed in by the client (UTF8).
    116  *   szDomain         Domain passed in by the client (UTF8).
    117  *   fLogon           Boolean flag. Indicates whether the entry point is called
    118  *                    for a client logon or the client disconnect.
    119  *   clientId         Server side unique identifier of the client.
     125 * @retval AuthAccessDenied    Client access has been denied.
     126 * @retval AuthAccessGranted   Client has the right to use the virtual machine.
     127 * @retval AuthDelegateToGuest Guest operating system must
     128 *                             authenticate the client and the
     129 *                             library must be called again with
     130 *                             the result of the guest authentication.
    120131 *
    121  * Return code:
    122  *
    123  *   AuthAccessDenied    Client access has been denied.
    124  *   AuthAccessGranted   Client has the right to use the
    125  *                       virtual machine.
    126  *   AuthDelegateToGuest Guest operating system must
    127  *                       authenticate the client and the
    128  *                       library must be called again with
    129  *                       the result of the guest
    130  *                       authentication.
    131  *
    132  * Note: When 'fLogon' is 0, only pUuid and clientId are valid and the return
    133  *       code is ignored.
     132 * @note When @a fLogon is 0, only @a pUuid and @a clientId are valid and the
     133 *       return code is ignored.
    134134 */
    135 typedef AuthResult AUTHCALL AUTHENTRY2(PAUTHUUID pUuid,
    136                                        AuthGuestJudgement guestJudgement,
    137                                        const char *szUser,
    138                                        const char *szPassword,
    139                                        const char *szDomain,
    140                                        int fLogon,
    141                                        unsigned clientId);
    142 
    143 
    144 typedef AUTHENTRY2 *PAUTHENTRY2;
    145 
     135typedef AuthResult AUTHCALL FNAUTHENTRY2(PAUTHUUID pUuid,
     136                                         AuthGuestJudgement guestJudgement,
     137                                         const char *szUser,
     138                                         const char *szPassword,
     139                                         const char *szDomain,
     140                                         int fLogon,
     141                                         unsigned clientId);
     142/** Pointer to a FNAUTHENTRY2 function. */
     143typedef FNAUTHENTRY2 *PFNAUTHENTRY2;
     144/** @deprecated   */
     145typedef FNAUTHENTRY2  AUTHENTRY2;
     146/** @deprecated   */
     147typedef PFNAUTHENTRY2 PAUTHENTRY2;
     148/** Name of the FNAUTHENTRY2 entry point. */
    146149#define AUTHENTRY2_NAME "VRDPAuth2"
    147150
    … …  
    149152 * Authentication library entry point version 3.
    150153 *
    151  * Parameters:
     154 * @param  szCaller         The name of the component which calls the library (UTF8).
     155 * @param  pUuid            Pointer to the UUID of the accessed virtual machine. Can be NULL.
     156 * @param  guestJudgement   Result of the guest authentication.
     157 * @param  szUser           User name passed in by the client (UTF8).
     158 * @param  szPassword       Password passed in by the client (UTF8).
     159 * @param  szDomain         Domain passed in by the client (UTF8).
     160 * @param  fLogon           Boolean flag. Indicates whether the entry point is
     161 *                          called for a client logon or the client disconnect.
     162 * @param  clientId         Server side unique identifier of the client.
    152163 *
    153  *   szCaller         The name of the component which calls the library (UTF8).
    154  *   pUuid            Pointer to the UUID of the accessed virtual machine. Can be NULL.
    155  *   guestJudgement   Result of the guest authentication.
    156  *   szUser           User name passed in by the client (UTF8).
    157  *   szPassword       Password passed in by the client (UTF8).
    158  *   szDomain         Domain passed in by the client (UTF8).
    159  *   fLogon           Boolean flag. Indicates whether the entry point is called
    160  *                    for a client logon or the client disconnect.
    161  *   clientId         Server side unique identifier of the client.
     164 * @retval AuthResultAccessDenied    Client access has been denied.
     165 * @retval AuthResultAccessGranted   Client has the right to use the
     166 *                                   virtual machine.
     167 * @retval AuthResultDelegateToGuest Guest operating system must
     168 *                                   authenticate the client and the
     169 *                                   library must be called again with
     170 *                                   the result of the guest
     171 *                                   authentication.
    162172 *
    163  * Return code:
    164  *
    165  *   AuthResultAccessDenied    Client access has been denied.
    166  *   AuthResultAccessGranted   Client has the right to use the
    167  *                             virtual machine.
    168  *   AuthResultDelegateToGuest Guest operating system must
    169  *                             authenticate the client and the
    170  *                             library must be called again with
    171  *                             the result of the guest
    172  *                             authentication.
    173  *
    174  * Note: When 'fLogon' is 0, only pszCaller, pUuid and clientId are valid and the return
    175  *       code is ignored.
     173 * @note When @a fLogon is 0, only @a pszCaller, @a pUuid and @a clientId are
     174 *       valid and the return code is ignored.
    176175 */
    177 typedef AuthResult AUTHCALL AUTHENTRY3(const char *szCaller,
    178                                        PAUTHUUID pUuid,
    179                                        AuthGuestJudgement guestJudgement,
    180                                        const char *szUser,
    181                                        const char *szPassword,
    182                                        const char *szDomain,
    183                                        int fLogon,
    184                                        unsigned clientId);
     176typedef AuthResult AUTHCALL FNAUTHENTRY3(const char *szCaller,
     177                                         PAUTHUUID pUuid,
     178                                         AuthGuestJudgement guestJudgement,
     179                                         const char *szUser,
     180                                         const char *szPassword,
     181                                         const char *szDomain,
     182                                         int fLogon,
     183                                         unsigned clientId);
     184/** Pointer to a FNAUTHENTRY3 function. */
     185typedef FNAUTHENTRY3 *PFNAUTHENTRY3;
     186/** @deprecated */
     187typedef FNAUTHENTRY3  AUTHENTRY3;
     188/** @deprecated */
     189typedef PFNAUTHENTRY3 PAUTHENTRY3;
    185190
    186 
    187 typedef AUTHENTRY3 *PAUTHENTRY3;
    188 
     191/** Name of the FNAUTHENTRY3 entry point. */
    189192#define AUTHENTRY3_NAME "AuthEntry"
    190193
     194/** @} */
     195
    191196#endif
Note: See TracChangeset for help on using the changeset viewer.

© 2025 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette