From b10510893955966f36cd8aa0229bfcac6db14055 Mon Sep 17 00:00:00 2001 From: Günther Deschner Date: Wed, 16 Apr 2008 10:03:06 +0200 Subject: libnetapi: Add initial inline doxygen comments. Guenther (This used to be commit 01bc4b6ac03b98c2371b4dfc0948f5ef8d06bcbc) --- source3/lib/netapi/netapi.h | 231 +++++++++++++++++++++++++++++++++++++------- 1 file changed, 195 insertions(+), 36 deletions(-) diff --git a/source3/lib/netapi/netapi.h b/source3/lib/netapi/netapi.h index e93381533b..e9fcc3777a 100644 --- a/source3/lib/netapi/netapi.h +++ b/source3/lib/netapi/netapi.h @@ -179,9 +179,23 @@ const char *libnetapi_get_error_string(struct libnetapi_ctx *ctx, NET_API_STATUS NetApiBufferFree(void *buffer); -/**************************************************************** - NetJoinDomain -****************************************************************/ +/************************************************************//** + * + * NetJoinDomain + * + * @brief Join a computer to a domain or workgroup + * + * @param[in] server The server name to connect to + * @param[in] domain The domain or workgroup to join + * @param[in] account_ou The organizational Unit to create the computer account + * in (AD only) + * @param[in] account The domain account used for joining a domain + * @param[in] password The domain account's password used for joining a domain + * @param[in] join_flags Bitmask field to define specific join features + * @return NET_API_STATUS + * + * example netdomjoin/netdomjoin.c + ***************************************************************/ NET_API_STATUS NetJoinDomain(const char * server /* [in] */, const char * domain /* [in] [ref] */, @@ -190,26 +204,62 @@ NET_API_STATUS NetJoinDomain(const char * server /* [in] */, const char * password /* [in] */, uint32_t join_flags /* [in] */); -/**************************************************************** - NetUnjoinDomain -****************************************************************/ +/************************************************************//** + * + * NetUnjoinDomain + * + * @brief Unjoin a computer from a domain or workgroup + * + * @param[in] server_name The server name to connect to + * @param[in] account The domain account used for unjoining a domain + * @param[in] password The domain account's password used for unjoining a domain + * @param[in] unjoin_flags Bitmask field to define specific unjoin features + * @return NET_API_STATUS + * + ***************************************************************/ NET_API_STATUS NetUnjoinDomain(const char * server_name /* [in] */, const char * account /* [in] */, const char * password /* [in] */, uint32_t unjoin_flags /* [in] */); -/**************************************************************** - NetGetJoinInformation -****************************************************************/ +/************************************************************//** + * + * NetGetJoinInformation + * + * @brief Unjoin a computer from a domain or workgroup + * + * @param[in] server_name The server name to connect to + * @param[out] name_buffer Returns the name of the workgroup or domain + * @param[out] name_type Returns the type of that name + * @return NET_API_STATUS + * + * example netdomjoin-gui/netdomjoin-gui.c + * + ***************************************************************/ NET_API_STATUS NetGetJoinInformation(const char * server_name /* [in] */, const char * *name_buffer /* [out] [ref] */, uint16_t *name_type /* [out] [ref] */); -/**************************************************************** - NetGetJoinableOUs -****************************************************************/ +/************************************************************//** + * + * NetGetJoinableOUs + * + * @brief Query for the list of joinable organizational Units that can be used + * for joining AD + * + * @param[in] server_name The server name to connect to + * @param[in] domain The AD domain to query + * @param[in] account The domain account used for the query + * @param[in] password The domain account's password used for the query + * @param[out] ou_count The number of ous returned + * @param[out] ous Returned string array containing the ous + * @return NET_API_STATUS + * + * example netdomjoin-gui/netdomjoin-gui.c + * + ***************************************************************/ NET_API_STATUS NetGetJoinableOUs(const char * server_name /* [in] */, const char * domain /* [in] [ref] */, @@ -218,43 +268,95 @@ NET_API_STATUS NetGetJoinableOUs(const char * server_name /* [in] */, uint32_t *ou_count /* [out] [ref] */, const char * **ous /* [out] [ref] */); -/**************************************************************** - NetServerGetInfo -****************************************************************/ +/************************************************************//** + * + * NetServerGetInfo + * + * @brief Get Information on a server + * + * @param[in] server_name The server name to connect to + * @param[in] level The level to define which information is requested + * @param[out] buffer The returned buffer carrying the SERVER_INFO structure + * @return NET_API_STATUS + * + ***************************************************************/ NET_API_STATUS NetServerGetInfo(const char * server_name /* [in] */, uint32_t level /* [in] */, uint8_t **buffer /* [out] [ref] */); -/**************************************************************** - NetServerSetInfo -****************************************************************/ +/************************************************************//** + * + * NetServerSetInfo + * + * @brief Get Information on a server + * + * @param[in] server_name The server name to connect to + * @param[in] level The level to define which information is set + * @param[in] buffer The buffer carrying the SERVER_INFO structure + * @param[out] parm_error On failure returns the invalid SERVER_INFO member + * @return NET_API_STATUS + * + ***************************************************************/ NET_API_STATUS NetServerSetInfo(const char * server_name /* [in] */, uint32_t level /* [in] */, uint8_t *buffer /* [in] [ref] */, uint32_t *parm_error /* [out] [ref] */); -/**************************************************************** - NetGetDCName -****************************************************************/ +/************************************************************//** + * + * NetGetDCName + * + * @brief Query for the PDC for a given domain + * + * @param[in] server_name The server name to connect to + * @param[in] domain_name The name of the domain to lookup + * @param[out] buffer The name of the domain to lookup + * @return NET_API_STATUS + * + * example getdc/getdc.c + ***************************************************************/ NET_API_STATUS NetGetDCName(const char * server_name /* [in] */, const char * domain_name /* [in] */, uint8_t **buffer /* [out] [ref] */); -/**************************************************************** - NetGetAnyDCName -****************************************************************/ +/************************************************************//** + * + * NetGetAnyDCName + * + * @brief Query for any DC for a given domain + * + * @param[in] server_name The server name to connect to + * @param[in] domain_name The name of the domain to lookup + * @param[out] buffer The name of the domain to lookup + * @return NET_API_STATUS + * + * example getdc/getdc.c + ***************************************************************/ NET_API_STATUS NetGetAnyDCName(const char * server_name /* [in] */, const char * domain_name /* [in] */, uint8_t **buffer /* [out] [ref] */); -/**************************************************************** - DsGetDcName -****************************************************************/ +/************************************************************//** + * + * DsGetDcName + * + * @brief Lookup a DC for a given domain and return information structure + * + * @param[in] server_name The server name to connect to + * @param[in] domain_name The name of the domain to lookup (cannot be NULL) + * @param[in] domain_guid The GUID of the domain to lookup (optional) + * @param[in] site_name The name of the site the DC should reside in + * @param[in] flags A bitmask to request specific features supported by the DC + * @param[out] dc_info Pointer to a DOMAIN_CONTROLLER_INFO structure + * @return NET_API_STATUS + * + * example dsgetdc/dsgetdc.c + ***************************************************************/ NET_API_STATUS DsGetDcName(const char * server_name /* [in] [unique] */, const char * domain_name /* [in] [ref] */, @@ -263,25 +365,64 @@ NET_API_STATUS DsGetDcName(const char * server_name /* [in] [unique] */, uint32_t flags /* [in] */, struct DOMAIN_CONTROLLER_INFO **dc_info /* [out] [ref] */); -/**************************************************************** - NetUserAdd -****************************************************************/ +/************************************************************//** + * + * NetUserAdd + * + * @brief Create a user on a given server + * + * @param[in] server_name The server name to connect to + * @param[in] level The level of the USER_INFO structure passed in (Currently + * only level 1 is supported) + * @param[in] buffer The buffer carrying the USER_INFO structure + * @param[out] parm_error In case of error returns the failing member of the + * structure + * @return NET_API_STATUS + * + * example user/user_add.c + ***************************************************************/ NET_API_STATUS NetUserAdd(const char * server_name /* [in] */, uint32_t level /* [in] */, uint8_t *buffer /* [in] [ref] */, uint32_t *parm_error /* [out] [ref] */); -/**************************************************************** - NetUserDel -****************************************************************/ +/************************************************************//** + * + * NetUserDel + * + * @brief Delete a user on a given server + * + * @param[in] server_name The server name to connect to + * @param[in] user_name The user account to delete + * @return NET_API_STATUS + * + * example user/user_del.c + ***************************************************************/ NET_API_STATUS NetUserDel(const char * server_name /* [in] */, const char * user_name /* [in] */); -/**************************************************************** - NetUserEnum -****************************************************************/ +/************************************************************//** + * + * NetUserEnum + * + * @brief Enumerate accounts on a server + * + * @param[in] server_name The server name to connect to + * @param[in] level The enumeration level used for the query (Currently only + * level 0 is supported) + * @param[in] filter The account flags filter used for the query + * @param[out] buffer The returned enumeration buffer + * @param[in] prefmaxlen The requested maximal buffer size + * @param[out] entries_read The number of returned entries + * @param[out] total_entries The number of total entries + * @param[in,out] resume_handle A handle passed in and returned for resuming + * operations + * @return NET_API_STATUS + * + * example user/user_enum.c + ***************************************************************/ NET_API_STATUS NetUserEnum(const char * server_name /* [in] */, uint32_t level /* [in] */, @@ -292,6 +433,24 @@ NET_API_STATUS NetUserEnum(const char * server_name /* [in] */, uint32_t *total_entries /* [out] [ref] */, uint32_t *resume_handle /* [in,out] [ref] */); +/************************************************************//** + * + * NetQueryDisplayInformation + * + * @brief Enumerate accounts on a server + * + * @param[in] server_name The server name to connect to + * @param[in] level The enumeration level used for the query + * @param[in] idx The index to start the the display enumeration at + * @param[in] entries_requested The number of entries requested + * @param[in] prefmaxlen The requested maximal buffer size + * @param[out] entries_read The number of returned entries + * @param[out] buffer The returned display information buffer + * @return NET_API_STATUS + * + * example user/user_dispinfo.c + ***************************************************************/ + NET_API_STATUS NetQueryDisplayInformation(const char * server_name /* [in] [unique] */, uint32_t level /* [in] */, uint32_t idx /* [in] */, -- cgit