libnetapi: Add initial inline doxygen comments.

Guenther
(This used to be commit 01bc4b6ac03b98c2371b4dfc0948f5ef8d06bcbc)

1 files 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] */,