From ece792ff5716992effdfd9db864d646e7c7ec0a6 Mon Sep 17 00:00:00 2001 From: Chris Sherlock Date: Sat, 18 Mar 2017 02:40:23 +1100 Subject: osl: more doxygen changes Change-Id: Ic191ef5694cef24f030b8e1dba3e66d5e7fb3584 --- include/osl/socket.h | 118 +++++++++++++++++++++++++-------------------------- include/osl/time.h | 2 +- 2 files changed, 58 insertions(+), 62 deletions(-) (limited to 'include/osl') diff --git a/include/osl/socket.h b/include/osl/socket.h index 6ee3b9b2bb68..799fa81762b9 100644 --- a/include/osl/socket.h +++ b/include/osl/socket.h @@ -212,8 +212,8 @@ SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_copySocketAddr( oslSocketAddr Addr); /** Compares the values of two SocketAddresses. - @return sal_True if both addresses denote the same socket address, - sal_False otherwise. + @retval sal_True if both addresses denote the same socket address. + @retval sal_False if both addresses do not denote the same socket address. */ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isEqualSocketAddr( oslSocketAddr Addr1, oslSocketAddr Addr2); @@ -233,7 +233,7 @@ SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_resolveHostname( @see oslSocketAddr @param[in] strDottedAddr dotted decimal internet address, may be 0. @param[in] Port port number in host byte order. - @return 0 if address could not be created. + @retval 0 if address could not be created. */ SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_createInetBroadcastAddr ( rtl_uString *strDottedAddr, sal_Int32 Port); @@ -244,7 +244,7 @@ SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_createInetBroadcastAddr ( (e.g. "141.99.128.50"). @param strDottedAddr [in] String with dotted address. @param Port [in] portnumber in host byte order. - @return 0 if address could not be created. + @retval 0 if address could not be created. */ SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_createInetSocketAddr ( rtl_uString *strDottedAddr, sal_Int32 Port); @@ -258,7 +258,7 @@ SAL_DLLPUBLIC void SAL_CALL osl_destroySocketAddr( /** Looks up the port-number designated to the specified service/protocol-pair. (e.g. "ftp" "tcp"). - @return OSL_INVALID_PORT if no appropriate entry was found, otherwise the port-number. + @retval OSL_INVALID_PORT if no appropriate entry was found, otherwise the port-number. */ SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_getServicePort( rtl_uString *strServicename, rtl_uString *strProtocol); @@ -284,7 +284,7 @@ SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_getInetPortOfSocketAddr( /** Sets the Port of Addr. @param[in] Addr the SocketAddr to perfom the operation on. @param[in] Port is expected in host byte-order. - @return sal_False if Addr is not an inet-addr. + @retval sal_False if Addr is not an inet-addr. */ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_setInetPortOfSocketAddr( oslSocketAddr Addr, sal_Int32 Port); @@ -305,7 +305,8 @@ SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_getHostnameOfSocketAddr( (e.g. 141.99.20.34) represented by the address. If the address is invalid or not of type osl_Socket_FamilyInet, it returns 0. - @return osl_Socket_Ok or osl_Socket_Error + @retval osl_Socket_Ok + @retval osl_Socket_Error */ SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_getDottedInetAddrOfSocketAddr( oslSocketAddr Addr, rtl_uString **strDottedInetAddr); @@ -319,7 +320,8 @@ SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_setAddrOfSocketAddr( @param[in] Addr The socket address from which to extract the ipaddress. @param[out] ppByteSeq After the call, *ppByteSeq contains the ipaddress in network byteorder. *ppByteSeq may be 0 in case of an invalid socket handle. - @return osl_Socket_Ok or osl_Socket_Error + @retval osl_Socket_Ok + @retval osl_Socket_Error */ SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_getAddrOfSocketAddr( oslSocketAddr Addr, sal_Sequence **ppByteSeq ); @@ -385,7 +387,8 @@ SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_getSocketAddrOfHostAddr(const oslHostAd /** Retrieve this machines hostname. May not always be a fully qualified domain name (FQDN). @param strLocalHostname out-parameter. The string that receives the local host name. - @return sal_True upon success, sal_False otherwise. + @retval sal_True upon success + @retval sal_False */ SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_getLocalHostname(rtl_uString **strLocalHostname); @@ -416,7 +419,7 @@ SAL_DLLPUBLIC void SAL_CALL osl_releaseSocket( oslSocket Socket ); /** Create a socket of the specified Family and Type. The semantic of the Protocol parameter depends on the given family and type. - @return 0 if socket could not be created, otherwise you get a handle + @retval 0 if socket could not be created, otherwise you get a handle to the allocated socket-datastructure. */ SAL_DLLPUBLIC oslSocket SAL_CALL osl_createSocket( @@ -427,7 +430,7 @@ SAL_DLLPUBLIC oslSocket SAL_CALL osl_createSocket( /** Retrieves the Address of the local end of the socket. Note that a socket must be bound or connected before a valid address can be returned. - @return 0 if socket-address could not be created, otherwise you get + @retval 0 if socket-address could not be created, otherwise you get the created Socket-Address. */ SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_getLocalAddrOfSocket(oslSocket Socket); @@ -435,7 +438,7 @@ SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_getLocalAddrOfSocket(oslSocket Socket); /** Retrieves the Address of the remote end of the socket. Note that a socket must be connected before a valid address can be returned. - @return 0 if socket-address could not be created, otherwise you get + @retval 0 if socket-address could not be created, otherwise you get the created Socket-Address. */ SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_getPeerAddrOfSocket(oslSocket Socket); @@ -443,7 +446,8 @@ SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_getPeerAddrOfSocket(oslSocket Socket); /** Binds the given address to the socket. @param[in] Socket @param[in] Addr - @return sal_False if the bind failed, sal_True if successful. + @retval sal_False if the bind failed + @retval sal_True if bind is successful @see osl_getLastSocketError() */ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_bindAddrToSocket( @@ -456,10 +460,10 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_bindAddrToSocket( @param[in] Addr the peer address. @param pTimeout Timeout value or NULL for blocking. - @return osl_Socket_Ok on successful connection, - osl_Socket_TimedOut if operation timed out, - osl_Socket_Interrupted if operation was interrupted - osl_Socket_Error if the connection failed. + @retval osl_Socket_Ok on successful connection, + @retval osl_Socket_TimedOut if operation timed out, + @retval osl_Socket_Interrupted if operation was interrupted + @retval osl_Socket_Error if the connection failed. */ SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_connectSocketTo( oslSocket Socket, @@ -473,7 +477,7 @@ SAL_DLLPUBLIC oslSocketResult SAL_CALL osl_connectSocketTo( @param[in] MaxPendingConnections denotes the length of the queue of pending connections for this socket. If MaxPendingConnections is -1, the systems default value will be used (Usually 5). - @return sal_False if the listen failed. + @retval sal_False if the listen failed. */ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_listenOnSocket( oslSocket Socket, @@ -484,7 +488,7 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_listenOnSocket( This call blocks if there is no incoming connection present. @param[in] Socket The socket to accept the connection on. @param[in] pAddr if pAddr is != 0, the peers address is returned. - @return 0 if the accept-call failed, otherwise you get a socket + @retval 0 if the accept-call failed, otherwise you get a socket representing the new connection. */ SAL_DLLPUBLIC oslSocket SAL_CALL osl_acceptConnectionOnSocket @@ -501,13 +505,11 @@ SAL_DLLPUBLIC oslSocket SAL_CALL osl_acceptConnectionOnSocket @param[in] BytesToRead The number of bytes to read. pBuffer must have at least this size. @param[in] Flag Modifier for the call. Valid values are: - + osl_Socket_MsgNormal + osl_Socket_MsgOOB + osl_Socket_MsgPeek + osl_Socket_MsgDontRoute + osl_Socket_MsgMaxIOVLen @return the number of received bytes. */ @@ -529,13 +531,11 @@ SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_receiveSocket( datagram. @param[in] BufferSize The size of pBuffer. @param[in] Flag Modifier for the call. Valid values are: - + osl_Socket_MsgNormal + osl_Socket_MsgOOB + osl_Socket_MsgPeek + osl_Socket_MsgDontRoute + osl_Socket_MsgMaxIOVLen @return the number of received bytes. */ @@ -554,13 +554,11 @@ SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_receiveFromSocket( @param[in] BytesToSend The number of bytes to send. pBuffer must have at least this size. @param[in] Flag Modifier for the call. Valid values are: - @return the number of transferred bytes. */ @@ -585,13 +583,11 @@ SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_sendSocket( @param[in] BytesToSend The number of bytes to send. pBuffer must have at least this size. @param Flag [in] Modifier for the call. Valid values are: - @return the number of transferred bytes. */ @@ -607,8 +603,9 @@ SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_sendToSocket( You can specify a timeout-value in seconds/microseconds that denotes how long the operation will block if the Socket is not ready. - @return sal_True if read operations (recv, recvFrom, accept) on the Socket - will NOT block; sal_False if it would block or if an error occurred. + @retval sal_True if read operations (recv, recvFrom, accept) on the Socket + will NOT block; + @retval sal_False if it would block or if an error occurred. @param Socket the Socket to perfom the operation on. @param pTimeout if NULL, the operation will block without a timeout. @@ -619,8 +616,9 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isReceiveReady( /** Checks if send operations will block. You can specify a timeout-value in seconds/microseconds that denotes how long the operation will block if the Socket is not ready. - @return sal_True if send operations (send, sendTo) on the Socket - will NOT block; sal_False if it would block or if an error occurred. + @retval sal_True if send operations (send, sendTo) on the Socket + will NOT block + @retval sal_False if it would block or if an error occurred. @param Socket the Socket to perfom the operation on. @param pTimeout if NULL, the operation will block without a timeout. Otherwise @@ -632,8 +630,9 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isSendReady( /** Checks if a request for out-of-band data will block. You can specify a timeout-value in seconds/microseconds that denotes how long the operation will block if the Socket has no pending OOB data. - @return sal_True if OOB-request operations (recv with appropriate flags) - on the Socket will NOT block; sal_False if it would block or if an error occurred. + @retval sal_True if OOB-request operations (recv with appropriate flags) + on the Socket will NOT block + @retval sal_False if it would block or if an error occurred. @param Socket the Socket to perfom the operation on. @param pTimeout if NULL, the operation will block without a timeout. @@ -763,7 +762,7 @@ SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_getSocketOption( oslSocket Socket, @param BufferLen contains the length of the Buffer. - @return True if the option could be changed. + @retval True if the option could be changed. */ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_setSocketOption( oslSocket Socket, oslSocketOptionLevel Level, @@ -773,9 +772,9 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_setSocketOption( oslSocket Socket, /** Enables/disables non-blocking-mode of the socket. @param Socket Change mode for this socket. - @param On sal_True enables non-blocking mode, - sal_False disables non-blocking mode. - @return sal_True if mode could be changed. + @param On sal_True enables non-blocking mode, + sal_False disables non-blocking mode. + @retval sal_True if mode could be changed. */ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_enableNonBlockingMode( oslSocket Socket, sal_Bool On); @@ -783,7 +782,7 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_enableNonBlockingMode( /** Query state of non-blocking-mode of the socket. @param Socket Query mode for this socket. - @return True if non-blocking-mode is enabled. + @retval True if non-blocking-mode is enabled. */ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isNonBlockingMode( oslSocket Socket); @@ -791,15 +790,12 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isNonBlockingMode( /** Queries the socket for its type. @param[in] Socket The socket to query. - @return one of: - + @retval osl_Socket_TypeStream + @retval osl_Socket_TypeDgram + @retval osl_Socket_TypeRaw + @retval osl_Socket_TypeRdm + @retval osl_Socket_TypeSeqPacket + @retval osl_invalid_SocketType if an error occurred */ SAL_DLLPUBLIC oslSocketType SAL_CALL osl_getSocketType( oslSocket Socket); @@ -812,9 +808,9 @@ SAL_DLLPUBLIC void SAL_CALL osl_getLastSocketErrorDescription( oslSocket Socket, rtl_uString **strError); /** returns a constant describing the last error for the socket system. - @return osl_Socket_E_NONE if no error occurred, - osl_invalid_SocketError if an unknown (unmapped) - error occurred, otherwise an enum describing the error. + @retval osl_Socket_E_NONE if no error occurred + @retval osl_invalid_SocketError if an unknown (unmapped) + error occurred, otherwise an enum describing the error. */ SAL_DLLPUBLIC oslSocketError SAL_CALL osl_getLastSocketError( oslSocket Socket); @@ -853,7 +849,7 @@ SAL_DLLPUBLIC void SAL_CALL osl_removeFromSocketSet(oslSocketSet Set, oslSocket /** Checks if socket is in the set. @param Set the set to be checked. @param Socket check if this socket is in the set. - @return sal_True if socket is in the set. + @retval sal_True if socket is in the set. */ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isInSocketSet(oslSocketSet Set, oslSocket Socket); diff --git a/include/osl/time.h b/include/osl/time.h index 965675301ef6..0a1834f4c93d 100644 --- a/include/osl/time.h +++ b/include/osl/time.h @@ -135,7 +135,7 @@ typedef struct _oslDateTime /** Get the current system time as TimeValue. - @return false if any error occurs. + @retval false if any error occurs. */ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_getSystemTime( TimeValue* pTimeVal ); -- cgit