From ba4831629e93bd6957ed8cfce9cec25f4f8ce5e4 Mon Sep 17 00:00:00 2001 From: Chris Sherlock Date: Fri, 23 Jun 2017 06:08:00 +1000 Subject: osl: doxygen fixes for headers Change-Id: I3f30b5ab985c2ff709116568905b941c5d50fd1a --- include/osl/file.h | 190 ++++++++++++++--------------- include/osl/file.hxx | 104 ++++++++-------- include/osl/module.hxx | 10 +- include/osl/mutex.h | 6 + include/osl/pipe_decl.hxx | 48 +++++--- include/osl/process.h | 135 +++++++++++---------- include/osl/profile.h | 4 +- include/osl/security_decl.hxx | 11 +- include/osl/signal.h | 5 +- include/osl/socket.h | 275 ++++++++++++++++++++---------------------- include/osl/socket_decl.hxx | 16 ++- include/osl/thread.hxx | 2 +- include/osl/time.h | 2 +- 13 files changed, 406 insertions(+), 402 deletions(-) diff --git a/include/osl/file.h b/include/osl/file.h index 9b9e31e5bf11..62601b747b55 100644 --- a/include/osl/file.h +++ b/include/osl/file.h @@ -139,10 +139,10 @@ typedef void *oslDirectoryItem; /** Open a directory for enumerating its contents. - @param pustrDirectoryURL [in] + @param[in] pustrDirectoryURL The full qualified URL of the directory. - @param pDirectory [out] + @param[out] pDirectory On success it receives a handle used for subsequent calls by osl_getNextDirectoryItem(). The handle has to be released by a call to osl_closeDirectory(). @@ -168,14 +168,14 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_openDirectory( Retrieves the next item of a previously opened directory. All handles have an initial refcount of 1. - @param Directory [in] + @param[in] Directory A directory handle received from a previous call to osl_openDirectory(). - @param pItem [out] + @param[out] pItem On success it receives a handle that can be used for subsequent calls to osl_getFileStatus(). The handle has to be released by a call to osl_releaseDirectoryItem(). - @param uHint [in] + @param[in] uHint With this parameter the caller can tell the implementation that (s)he is going to call this function uHint times afterwards. This enables the implementation to get the information for more than one file and cache it until the next calls. @@ -200,7 +200,7 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_getNextDirectoryItem( /** Release a directory handle. - @param Directory [in] + @param[in] Directory A handle received by a call to osl_openDirectory(). @retval osl_File_E_None on success @@ -220,10 +220,10 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_closeDirectory( Due to performance issues it is not recommended to use this function while enumerating the contents of a directory. In this case use osl_getNextDirectoryItem() instead. - @param pustrFileURL [in] + @param[in] pustrFileURL An absolute file URL. - @param pItem [out] + @param[out] pItem On success it receives a handle which can be used for subsequent calls to osl_getFileStatus(). The handle has to be released by a call to osl_releaseDirectoryItem(). @@ -257,7 +257,7 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_getDirectoryItem( The caller responsible for releasing the directory item handle using osl_releaseDirectoryItem(). - @param Item [in] + @param[in] Item A handle received by a call to osl_getDirectoryItem() or osl_getNextDirectoryItem(). @retval osl_File_E_None on success @@ -278,7 +278,7 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_acquireDirectoryItem( If the refcount reaches 0 the data associated with this directory item handle will be released. - @param Item [in] + @param[in] Item A handle received by a call to osl_getDirectoryItem() or osl_getNextDirectoryItem(). @retval osl_File_E_None on success @@ -297,10 +297,10 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_releaseDirectoryItem( The comparison is done first by URL, and then by resolving links to find the target, and finally by comparing inodes on unix. - @param pItemA [in] + @param[in] pItemA A directory handle to compare with another handle - @param pItemB [in] + @param[in] pItemB A directory handle to compare with pItemA @retval sal_True if the items point to an identical resource @@ -392,15 +392,15 @@ typedef struct _oslFileStatus { /** Retrieve information about a single file or directory. - @param Item [in] + @param[in] Item A handle received by a previous call to osl_getDirectoryItem() or osl_getNextDirectoryItem(). - @param pStatus [in|out] + @param[in,out] pStatus Points to a structure which receives the information of the file or directory represented by the handle Item. The member uStructSize has to be initialized to sizeof(oslFileStatus) before calling this function. - @param uFieldMask [in] + @param[in] uFieldMask Specifies which fields of the structure pointed to by pStatus are of interest to the caller. @retval osl_File_E_None on success @@ -438,7 +438,7 @@ typedef void *oslVolumeDeviceHandle; Releases the given oslVolumeDeviceHandle which was acquired by a call to osl_getVolumeInformation() or osl_acquireVolumeDeviceHandle(). - @param Handle [in] + @param[in] Handle An oslVolumeDeviceHandle received by a call to osl_getVolumeInformation(). @retval @@ -459,7 +459,7 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_releaseVolumeDeviceHandle( osl_getVolumeInformation(). The caller is responsible for releasing the acquired handle by calling osl_releaseVolumeDeviceHandle(). - @param Handle [in] + @param[in] Handle An oslVolumeDeviceHandle received by a call to osl_getVolumeInformation(). @retval @@ -475,10 +475,10 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_acquireVolumeDeviceHandle( /** Get the full qualified URL where a device is mounted to. - @param Handle [in] + @param[in] Handle An oslVolumeDeviceHandle received by a call to osl_getVolumeInformation(). - @param ppustrDirectoryURL [out] + @param[out] ppustrDirectoryURL Receives the full qualified URL where the device is mounted to. @retval osl_File_E_None on success @@ -564,13 +564,13 @@ typedef struct _oslVolumeInfo { function osl_getFileStatus() should be called to determine if the type is osl_file_Type_Volume. - @param pustrDirectoryURL [in] + @param[in] pustrDirectoryURL Full qualified URL of the volume - @param pInfo [out] + @param[out] pInfo On success it receives information about the volume. - @param uFieldMask [in] + @param[in] uFieldMask Specifies which members of the structure should be filled @retval osl_File_E_None on success @@ -610,13 +610,13 @@ typedef void *oslFileHandle; Open a file. Only regular files can be openend. - @param pustrFileURL [in] + @param[in] pustrFileURL The full qualified URL of the file to open. - @param pHandle [out] + @param[out] pHandle On success it receives a handle to the open file. - @param uFlags [in] + @param[in] uFlags Specifies the open mode. On Android, if the file path is below the /assets folder, the file @@ -668,17 +668,17 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_openFile( /** Set the internal position pointer of an open file. - @param Handle [in] + @param[in] Handle Handle to a file received by a previous call to osl_openFile(). - @param uHow [in] + @param[in] uHow How to calculate the offset - osl_Pos_Absolut means start at the beginning of the file, osl_Pos_Current means offset from the current seek position and osl_Pos_End means the offset will be negative and the position will be calculated backwards from the end of the file by the offset provided. - @param uPos [in] + @param[in] uPos Seek offset, depending on uHow. If uHow is osl_Pos_End then the value must be negative. @retval osl_File_E_None on success @@ -695,10 +695,10 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_setFilePos( /** Retrieve the current position of the internal pointer of an open file. - @param Handle [in] + @param[in] Handle Handle to a file received by a previous call to osl_openFile(). - @param pPos [out] + @param[out] pPos On success receives the current position of the file pointer. @retval osl_File_E_None on success @@ -719,10 +719,10 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_getFilePos( Sets the file size of an open file. The file can be truncated or enlarged by the function. The position of the file pointer is not affeced by this function. - @param Handle [in] + @param[in] Handle Handle to a file received by a previous call to osl_openFile(). - @param uSize [in] + @param[in] uSize New size in bytes. @retval osl_File_E_None on success @@ -743,10 +743,10 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_setFileSize( Gets the file size of an open file. The position of the file pointer is not affeced by this function. - @param Handle [in] + @param[in] Handle Handle to a file received by a previous call to osl_openFile(). - @param pSize [out] + @param[out] pSize Current size in bytes. @retval osl_File_E_None on success @@ -791,11 +791,11 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_getFileSize( just a pointer to the file inside the already mapped .apk is returned. - @param Handle [in] Handle of the file to be mapped. - @param ppAddr [out] Memory address of the mapped file - @param uLength [in] Amount to map of the file from the offset - @param uOffset [in] Offset into the file to map - @param uFlags [in] osl_File_MapFlag_RandomAccess or + @param[in] Handle Handle of the file to be mapped. + @param[out] ppAddr Memory address of the mapped file + @param[in] uLength Amount to map of the file from the offset + @param[in] uOffset Offset into the file to map + @param[in] uFlags osl_File_MapFlag_RandomAccess or osl_File_MapFlag_WillNeed @retval osl_File_E_None on success @@ -872,17 +872,17 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_unmapMappedFile ( Reads a number of bytes from a file. The internal file pointer is increased by the number of bytes read. - @param Handle [in] + @param[in] Handle Handle to a file received by a previous call to osl_openFile(). - @param pBuffer [out] + @param[out] pBuffer Points to a buffer which receives data. The buffer must be large enough to hold uBytesRequested bytes. - @param uBytesRequested [in] + @param[in] uBytesRequested Number of bytes which should be retrieved. - @param pBytesRead [out] + @param[out] pBytesRead On success the number of bytes which have actually been retrieved. @retval osl_File_E_None on success @@ -905,10 +905,10 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_readFile( /** Test if the end of a file is reached. - @param Handle [in] + @param[in] Handle Handle to a file received by a previous call to osl_openFile(). - @param pIsEOF [out] + @param[out] pIsEOF Points to a variable that receives the end-of-file status. @retval osl_File_E_None on success @@ -934,16 +934,16 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_isEndOfFile( Writes a number of bytes to a file. The internal file pointer is increased by the number of bytes read. - @param Handle [in] + @param[in] Handle Handle to a file received by a previous call to osl_openFile(). - @param pBuffer [in] + @param[in] pBuffer Points to a buffer which contains the data. - @param uBytesToWrite [in] + @param[in] uBytesToWrite Number of bytes which should be written. - @param pBytesWritten [out] + @param[out] pBytesWritten On success the number of bytes which have actually been written. @retval osl_File_E_None on success @@ -971,20 +971,20 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_writeFile( The current position of the internal file pointer may or may not be changed. - @param Handle [in] + @param[in] Handle Handle to a file received by a previous call to osl_openFile(). - @param uOffset [in] + @param[in] uOffset Offset position from start of file where read starts - @param pBuffer [out] + @param[out] pBuffer Points to a buffer which receives data. The buffer must be large enough to hold uBytesRequested bytes. - @param uBytesRequested [in] + @param[in] uBytesRequested Number of bytes which should be retrieved. - @param pBytesRead [out] + @param[out] pBytesRead On success the number of bytes which have actually been retrieved. @retval osl_File_E_None on success @@ -1010,19 +1010,19 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_readFileAt( The current position of the internal file pointer may or may not be changed. - @param Handle [in] + @param[in] Handle Handle to a file received by a previous call to osl_openFile(). - @param uOffset [in] + @param[in] uOffset Position of file to write into. - @param pBuffer [in] + @param[in] pBuffer Points to a buffer which contains the data. - @param uBytesToWrite [in] + @param[in] uBytesToWrite Number of bytes which should be written. - @param pBytesWritten [out] + @param[out] pBytesWritten On success the number of bytes which have actually been written. @retval osl_File_E_None on success @@ -1052,10 +1052,10 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_writeFileAt( Reads a line from a file. The new line delimiter is NOT returned! - @param Handle [in] + @param[in] Handle Handle to a file received by a previous call to osl_openFile(). - @param ppSequence [in/out] + @param[in,out] ppSequence A pointer pointer to a sal_Sequence that will hold the line read on success. @retval osl_File_E_None on success @@ -1101,7 +1101,7 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_syncFile( oslFileHandle Handle ); /** Close an open file. - @param Handle [in] + @param[in] Handle Handle to a file received by a previous call to osl_openFile(). @retval osl_File_E_None on success @@ -1118,7 +1118,7 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_closeFile( oslFileHandle Handle ); /** Create a directory. - @param pustrDirectoryURL [in] + @param[in] pustrDirectoryURL Full qualified URL of the directory to create. @retval osl_File_E_None on success @@ -1162,7 +1162,7 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_createDirectoryWithFlags( /** Remove an empty directory. - @param pustrDirectoryURL [in] + @param[in] pustrDirectoryURL Full qualified URL of the directory. @retval osl_File_E_None on success @@ -1254,7 +1254,7 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_createDirectoryPath( /** Remove a regular file. - @param pustrFileURL [in] + @param[in] pustrFileURL Full qualified URL of the file to remove. @retval osl_File_E_None on success @@ -1286,10 +1286,10 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_removeFile( Copies a file to a new destination. Copies only files not directories. No assumptions should be made about preserving attributes or file time. - @param pustrSourceFileURL [in] + @param[in] pustrSourceFileURL Full qualified URL of the source file. - @param pustrDestFileURL [in] + @param[in] pustrDestFileURL Full qualified URL of the destination file. A directory is NOT a valid destination file! @retval osl_File_E_None on success @@ -1315,10 +1315,10 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_copyFile( Moves a file or directory to a new destination or renames it. File time and attributes are preserved. - @param pustrSourceFileURL [in] + @param[in] pustrSourceFileURL Full qualified URL of the source file. - @param pustrDestFileURL [in] + @param[in] pustrDestFileURL Full qualified URL of the destination file. An existing directory is NOT a valid destination ! @retval osl_File_E_None on success @@ -1344,10 +1344,10 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_moveFile( If a file or directory with the requested name already exists a new name is generated following the common rules on the actual Operating System and File System. - @param pustrRequestedURL [in] + @param[in] pustrRequestedURL Requested name of a file or directory. - @param ppustrValidURL [out] + @param[out] ppustrValidURL On success receives a name which is unused and valid on the actual Operating System and File System. @@ -1365,15 +1365,15 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_getCanonicalName( The function resolves symbolic links if possible and path ellipses, so on success the resulting absolute path is fully resolved. - @param pustrBaseDirectoryURL [in] + @param[in] pustrBaseDirectoryURL Base directory URL to which the relative path is related to. - @param pustrRelativeFileURL [in] + @param[in] pustrRelativeFileURL An URL of a file or directory relative to the directory path specified by pustrBaseDirectoryURL or an absolute path. If pustrRelativeFileURL denotes an absolute path pustrBaseDirectoryURL will be ignored. - @param ppustrAbsoluteFileURL [out] + @param[out] ppustrAbsoluteFileURL On success it receives the full qualified absolute file URL. @retval osl_File_E_None on success @@ -1399,10 +1399,10 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_getAbsoluteFileURL( /** Convert a system dependent path into a file URL. - @param pustrSystemPath [in] + @param[in] pustrSystemPath A System dependent path of a file or directory. - @param ppustrFileURL [out] + @param[out] ppustrFileURL On success it receives the file URL. @retval osl_File_E_None on success @@ -1415,10 +1415,10 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_getFileURLFromSystemPath( /** Search a full qualified system path or a file URL. - @param pustrFileName [in] + @param[in] pustrFileName A system dependent path, a file URL, a file or relative directory. - @param pustrSearchPath [in] + @param[in] pustrSearchPath A list of system paths, in which a given file has to be searched. The Notation of a path list is system dependent, e.g. on UNIX system "/usr/bin:/bin" and on Windows "C:\BIN;C:\BATCH". These paths are only for the search of a file or a relative path, otherwise it will be ignored. @@ -1428,7 +1428,7 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_getFileURLFromSystemPath( LD_LIBRARY_PATH) if the caller is not aware of the Operating System and so doesn't know which path list delimiter to use. - @param ppustrFileURL [out] + @param[out] ppustrFileURL On success it receives the full qualified file URL. @retval osl_File_E_None on success @@ -1444,10 +1444,10 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_searchFileURL( /** Convert a file URL into a system dependent path. - @param pustrFileURL [in] + @param[in] pustrFileURL A File URL. - @param ppustrSystemPath [out] + @param[out] ppustrSystemPath On success it receives the system path. @retval osl_File_E_None on success @@ -1460,7 +1460,7 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_getSystemPathFromFileURL( /** Function pointer representing the function called back from osl_abbreviateSystemPath - @param ustrText [in] + @param[in] ustrText Text to calculate the width for @return @@ -1473,16 +1473,16 @@ typedef sal_uInt32 (SAL_CALL *oslCalcTextWidthFunc)( rtl_uString *ustrText ); /** Abbreviate a system notation path. - @param ustrSystemPath [in] + @param[in] ustrSystemPath The full system path to abbreviate - @param pustrCompacted [out] + @param[out] pustrCompacted Receives the compacted system path on output - @param pCalcWidth [in] + @param[in] pCalcWidth Function ptr that calculates the width of a string. Can be zero. - @param uMaxWidth [in] + @param[in] uMaxWidth Maximum width allowed that is returned from pCalcWidth. If pCalcWidth is zero the character count is assumed as width. @@ -1498,10 +1498,10 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_abbreviateSystemPath( /** Set file attributes. - @param pustrFileURL [in] + @param[in] pustrFileURL The full qualified file URL. - @param uAttributes [in] + @param[in] uAttributes Attributes of the file to be set. @retval osl_File_E_None on success @@ -1514,16 +1514,16 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_setFileAttributes( /** Set the file time. - @param pustrFileURL [in] + @param[in] pustrFileURL The full qualified URL of the file. - @param aCreationTime [in] + @param[in] aCreationTime Creation time of the given file. - @param aLastAccessTime [in] + @param[in] aLastAccessTime Time of the last access of the given file. - @param aLastWriteTime [in] + @param[in] aLastWriteTime Time of the last modifying of the given file. @retval osl_File_E_None on success @@ -1570,15 +1570,15 @@ SAL_DLLPUBLIC oslFileError SAL_CALL osl_getTempDirURL( the file name will be returned, the caller is responsible for closing and removing the file. - @param pustrDirectoryURL [in] + @param[in] pustrDirectoryURL Specifies the full qualified URL where the temporary file should be created. If pustrDirectoryURL is 0 the path returned by osl_getTempDirURL will be used. - @param pHandle [out] + @param[out] pHandle On success receives a handle to the open file. If pHandle is 0 the file will be closed on return, in this case ppustrTempFileURL must not be 0. - @param ppustrTempFileURL [out] + @param[out] ppustrTempFileURL On success receives the full qualified URL of the temporary file. If ppustrTempFileURL is 0 the file will be automatically removed on close, in this case pHandle must not be 0. diff --git a/include/osl/file.hxx b/include/osl/file.hxx index 14c63e5cb657..f34633cb7222 100644 --- a/include/osl/file.hxx +++ b/include/osl/file.hxx @@ -113,10 +113,10 @@ public: If a file or directory with the requested name already exists a new name is generated following the common rules on the actual Operating System and File System. - @param ustrRequestedURL [in] + @param[in] ustrRequestedURL Requested name of a file or directory. - @param ustrValidURL [out] + @param[out] ustrValidURL On success receives a name which is unused and valid on the actual Operating System and File System. @@ -137,15 +137,15 @@ public: The function resolves symbolic links if possible and path ellipses, so on success the resulting absolute path is fully resolved. - @param ustrBaseDirectoryURL [in] + @param[in] ustrBaseDirectoryURL Base directory URL to which the relative path is related to. - @param ustrRelativeFileURL [in] + @param[in] ustrRelativeFileURL An URL of a file or directory relative to the directory path specified by ustrBaseDirectoryURL or an absolute path. If ustrRelativeFileURL denotes an absolute path ustrBaseDirectoryURL will be ignored. - @param ustrAbsoluteFileURL [out] + @param[out] ustrAbsoluteFileURL On success it receives the full qualified absolute file URL. @retval E_None on success @@ -172,10 +172,10 @@ public: /** Convert a file URL into a system dependent path. - @param ustrFileURL [in] + @param[in] ustrFileURL A File URL. - @param ustrSystemPath [out] + @param[out] ustrSystemPath On success it receives the system path. @retval E_None on success @@ -191,10 +191,10 @@ public: /** Convert a system dependent path into a file URL. - @param ustrSystemPath [in] + @param[in] ustrSystemPath A System dependent path of a file or directory. - @param ustrFileURL [out] + @param[out] ustrFileURL On success it receives the file URL. @retval E_None on success @@ -210,10 +210,10 @@ public: /** Searche a full qualified system path or a file URL. - @param ustrFileName [in] + @param[in] ustrFileName A system dependent path, a file URL, a file or relative directory - @param ustrSearchPath [in] + @param[in] ustrSearchPath A list of system paths, in which a given file has to be searched. The Notation of a path list is system dependent, e.g. on UNIX system "/usr/bin:/bin" and on Windows "C:\BIN;C:\BATCH". These paths are only for the search of a file or a relative path, otherwise it will be ignored. @@ -223,7 +223,7 @@ public: The value of an environment variable should be used (e.g. LD_LIBRARY_PATH) if the caller is not aware of the Operating System and so doesn't know which path list delimiter to use. - @param ustrFileURL [out] + @param[out] ustrFileURL On success it receives the full qualified file URL. @retval E_None on success @@ -262,16 +262,16 @@ public: it, the file will be automatically removed on close else the caller is responsible for removing the file on success.

- @param pustrDirectoryURL [in] + @param[in] pustrDirectoryURL Specifies the full qualified URL where the temporary file should be created. If pustrDirectoryURL is 0 the path returned by osl_getTempDirURL will be used. - @param pHandle [out] + @param[out] pHandle On success receives a handle to the open file. If pHandle is 0 the file will be closed on return, in this case pustrTempFileURL must not be 0. - @param pustrTempFileURL [out] + @param[out] pustrTempFileURL On success receives the full qualified URL of the temporary file. If pustrTempFileURL is 0 the file will be automatically removed on close, in this case pHandle must not be 0. @@ -912,7 +912,7 @@ public: /** Constructor. - @param ustrFileURL [in] + @param[in] ustrFileURL The full qualified URL of the file. Relative paths are not allowed. */ @@ -939,7 +939,7 @@ public: Open a file. Only regular files can be openend. - @param uFlags [in] + @param[in] uFlags Specifies the open mode. @retval E_None on success @@ -1010,10 +1010,10 @@ public: /** Set the internal position pointer of an open file. - @param uHow [in] + @param[in] uHow Distance to move the internal position pointer (from uPos). - @param uPos [in] + @param[in] uPos Absolute position from the beginning of the file. @retval E_None on success @@ -1031,7 +1031,7 @@ public: /** Retrieve the current position of the internal pointer of an open file. - @param uPos [out] + @param[out] uPos On success receives the current position of the file pointer. @retval E_None on success @@ -1051,7 +1051,7 @@ public: /** Test if the end of a file is reached. - @param pIsEOF [out] + @param[out] pIsEOF Points to a variable that receives the end-of-file status. @retval E_None on success @@ -1080,7 +1080,7 @@ public: Sets the file size of an open file. The file can be truncated or enlarged by the function. The position of the file pointer is not affeced by this function. - @param uSize [in] + @param[in] uSize New size in bytes. @retval E_None on success @@ -1102,7 +1102,7 @@ public: Gets the file size of an open file. The position of the file pointer is not affeced by this function. - @param rSize [out] + @param[out] rSize Current size in bytes. @retval E_None on success @@ -1126,14 +1126,14 @@ public: Reads a number of bytes from a file. The internal file pointer is increased by the number of bytes read. - @param pBuffer [out] + @param[out] pBuffer Points to a buffer which receives data. The buffer must be large enough to hold uBytesRequested bytes. - @param uBytesRequested [in] + @param[in] uBytesRequested Number of bytes which should be retrieved. - @param rBytesRead [out] + @param[out] rBytesRead On success the number of bytes which have actually been retrieved. @retval E_None on success @@ -1162,13 +1162,13 @@ public: Writes a number of bytes to a file. The internal file pointer is increased by the number of bytes read. - @param pBuffer [in] + @param[in] pBuffer Points to a buffer which contains the data. - @param uBytesToWrite [in] + @param[in] uBytesToWrite Number of bytes which should be written. - @param rBytesWritten [out] + @param[out] rBytesWritten On success the number of bytes which have actually been written. @retval E_None on success @@ -1200,7 +1200,7 @@ public: Reads a line from a file. The new line delimiter is NOT returned! - @param aSeq [in/out] + @param[in,out] aSeq A reference to a ::rtl::ByteSequence that will hold the line read on success. @retval E_None on success @@ -1254,10 +1254,10 @@ public: Copies a file to a new destination. Copies only files not directories. No assumptions should be made about preserving attributes or file time. - @param ustrSourceFileURL [in] + @param[in] ustrSourceFileURL Full qualified URL of the source file. - @param ustrDestFileURL [in] + @param[in] ustrDestFileURL Full qualified URL of the destination file. A directory is NOT a valid destination file! @retval E_None on success @@ -1284,10 +1284,10 @@ public: Moves a file or directory to a new destination or renames it. File time and attributes are preserved. - @param ustrSourceFileURL [in] + @param[in] ustrSourceFileURL Full qualified URL of the source file. - @param ustrDestFileURL [in] + @param[in] ustrDestFileURL Full qualified URL of the destination file. An existing directory is NOT a valid destination ! @retval E_None on success @@ -1309,7 +1309,7 @@ public: /** Remove a regular file. - @param ustrFileURL [in] + @param[in] ustrFileURL Full qualified URL of the file to remove. @retval E_None on success @@ -1341,10 +1341,10 @@ public: /** Set file attributes. - @param ustrFileURL [in] + @param[in] ustrFileURL The full qualified file URL. - @param uAttributes [in] + @param[in] uAttributes Attributes of the file to be set. @return @@ -1361,16 +1361,16 @@ public: /** Set the file time. - @param ustrFileURL [in] + @param[in] ustrFileURL The full qualified URL of the file. - @param rCreationTime [in] + @param[in] rCreationTime Creation time of the given file. - @param rLastAccessTime [in] + @param[in] rLastAccessTime Time of the last access of the given file. - @param rLastWriteTime [in] + @param[in] rLastWriteTime Time of the last modifying of the given file. @retval E_None on success @@ -1468,10 +1468,10 @@ public: Due to performance issues it is not recommended to use this function while enumerating the contents of a directory. In this case use osl_getNextDirectoryItem() instead. - @param ustrFileURL [in] + @param[in] ustrFileURL An absolute file URL. - @param rItem [out] + @param[out] rItem On success it receives a handle which can be used for subsequent calls to osl_getFileStatus(). The handle has to be released by a call to osl_releaseDirectoryItem(). @@ -1508,7 +1508,7 @@ public: /** Retrieve information about a single file or directory. - @param rStatus [in|out] + @param[in,out] rStatus Reference to a class which receives the information of the file or directory represented by this directory item. @@ -1626,7 +1626,7 @@ public: /** Constructor. - @param strPath [in] + @param[in] strPath The full qualified URL of the directory. Relative URLs are not allowed. */ @@ -1737,10 +1737,10 @@ public: Retrieves the next item of a previously opened directory. - @param rItem [out] + @param[out] rItem On success a valid DirectoryItem. - @param nHint [in] + @param[in] nHint With this parameter the caller can tell the implementation that (s)he is going to call this function uHint times afterwards. This enables the implementation to get the information for more than one file and cache it until the next calls. @@ -1771,10 +1771,10 @@ public: Retrieves information about a volume. A volume can either be a mount point, a network resource or a drive depending on Operating System and File System. - @param ustrDirectoryURL [in] + @param[in] ustrDirectoryURL Full qualified URL of the volume - @param rInfo [out] + @param[out] rInfo On success it receives information about the volume. @retval E_None on success @@ -1803,10 +1803,10 @@ public: /** Create a directory. - @param ustrDirectoryURL [in] + @param[in] ustrDirectoryURL Full qualified URL of the directory to create. - @param flags [in] + @param[in] flags Optional flags, see osl_createDirectoryWithFlags for details. This defaulted parameter is new since LibreOffice 4.3. @@ -1841,7 +1841,7 @@ public: /** Remove an empty directory. - @param ustrDirectoryURL [in] + @param[in] ustrDirectoryURL Full qualified URL of the directory. @retval E_None on success diff --git a/include/osl/module.hxx b/include/osl/module.hxx index cad8b587fd8f..d0bc0ff6c14a 100644 --- a/include/osl/module.hxx +++ b/include/osl/module.hxx @@ -45,11 +45,8 @@ public: Similar to getUrlFromAddress, but use a function address to get URL of the Module. Use Function pointer as symbol address to conceal type conversion. - @param addr - [in] function address in oslGenericFunction format. - - @param libraryUrl - [in|out] receives the URL of the module. + @param[in] addr function address in oslGenericFunction format. + @param[in,out] libraryUrl receives the URL of the module. @retval true on success @retval false can not get the URL from the specified function address or the parameter is invalid. @@ -134,8 +131,7 @@ public: getFunctionSymbol is an alternative function for getSymbol. Use Function pointer as symbol address to conceal type conversion. - @param ustrFunctionSymbolName - [in] Function name to be looked up. + @param[in] ustrFunctionSymbolName Function name to be looked up. @retval oslGenericFunction format function address on success @retval NULL lookup failed or parameter is somewhat invalid diff --git a/include/osl/mutex.h b/include/osl/mutex.h index 6cbfba15f026..8761f33737f7 100644 --- a/include/osl/mutex.h +++ b/include/osl/mutex.h @@ -33,11 +33,13 @@ struct _oslMutexImpl; typedef struct _oslMutexImpl * oslMutex; /** Create a mutex. + @return 0 if the mutex could not be created, otherwise a handle to the mutex. */ SAL_DLLPUBLIC oslMutex SAL_CALL osl_createMutex(void); /** Release the OS-structures and free mutex data-structure. + @param Mutex the mutex-handle */ SAL_DLLPUBLIC void SAL_CALL osl_destroyMutex(oslMutex Mutex); @@ -49,18 +51,22 @@ SAL_DLLPUBLIC void SAL_CALL osl_destroyMutex(oslMutex Mutex); SAL_DLLPUBLIC sal_Bool SAL_CALL osl_acquireMutex(oslMutex Mutex); /** Try to acquire the mutex without blocking. + @param Mutex handle to a created mutex. + @retval False if it could not be acquired. */ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_tryToAcquireMutex(oslMutex Mutex); /** Release the mutex. + @param Mutex handle to a created mutex. @retval False if system-call fails. */ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_releaseMutex(oslMutex Mutex); /** Returns a unique and global mutex. + @return the global mutex. */ SAL_DLLPUBLIC oslMutex * SAL_CALL osl_getGlobalMutex(void); diff --git a/include/osl/pipe_decl.hxx b/include/osl/pipe_decl.hxx index 738332456313..4de7bc8585ba 100644 --- a/include/osl/pipe_decl.hxx +++ b/include/osl/pipe_decl.hxx @@ -155,6 +155,7 @@ public: inline StreamPipe(); /** Creates pipe as wrapper around the underlying oslPipe. + @param Pipe */ inline StreamPipe(oslPipe Pipe); @@ -165,15 +166,17 @@ public: inline StreamPipe(const StreamPipe& Pipe); /** Creates a pipe. - @param strName - @param Options + + @param[in] strName Pipe name + @param[in] Options Pipe options */ inline StreamPipe(const ::rtl::OUString& strName, oslPipeOptions Options = osl_Pipe_OPEN); /** Creates a pipe. - @param strName - @param Options - @param rSec + + @param[in] strName Pipe name + @param[in] Options Pipe options + @param[in] rSec Security for the pipe */ inline StreamPipe(const ::rtl::OUString& strName, oslPipeOptions Options, const Security &rSec ); @@ -184,7 +187,8 @@ public: /** Attaches the oslPipe to this object. If the object already was attached to an oslPipe, the old one will be closed and destroyed. - @param Pipe + + @param[in] Pipe Pipe to attach to this object */ inline StreamPipe & SAL_CALL operator=(oslPipe Pipe); @@ -194,39 +198,45 @@ public: /** Tries to receives BytesToRead data from the connected pipe, - @param pBuffer [out] Points to a buffer that will be filled with the received - data. - @param BytesToRead [in] The number of bytes to read. pBuffer must have at least - this size. + @param[out] pBuffer Points to a buffer that will be filled with the received + data. + @param[in] BytesToRead The number of bytes to read. pBuffer must have at least + this size. + @return the number of received bytes. */ inline sal_Int32 SAL_CALL recv(void* pBuffer, sal_Int32 BytesToRead) const; /** Tries to sends BytesToSend data from the connected pipe. - @param pBuffer [in] Points to a buffer that contains the send-data. - @param BytesToSend [in] The number of bytes to send. pBuffer must have at least - this size. + @param[in] pBuffer Points to a buffer that contains the send-data. + @param[in] BytesToSend The number of bytes to send. pBuffer must have at least + this size. + @return the number of transferred bytes. */ inline sal_Int32 SAL_CALL send(const void* pBuffer, sal_Int32 BytesToSend) const; /** Retrieves n bytes from the stream and copies them into pBuffer. The method avoids incomplete reads due to packet boundaries. - @param pBuffer receives the read data. - @param n the number of bytes to read. pBuffer must be large enough + + @param[in] pBuffer receives the read data. + @param[in] n the number of bytes to read. pBuffer must be large enough to hold the n bytes! + @return the number of read bytes. The number will only be smaller than - n if an exceptional condition (e.g. connection closed) occurs. + n if an exceptional condition (e.g. connection closed) occurs. */ inline sal_Int32 SAL_CALL read(void* pBuffer, sal_Int32 n) const; /** Writes n bytes from pBuffer to the stream. The method avoids incomplete writes due to packet boundaries. - @param pBuffer contains the data to be written. - @param n the number of bytes to write. + + @param[in] pBuffer contains the data to be written. + @param[in] n the number of bytes to write. + @return the number of written bytes. The number will only be smaller than - n if an exceptional condition (e.g. connection closed) occurs. + n if an exceptional condition (e.g. connection closed) occurs. */ sal_Int32 SAL_CALL write(const void* pBuffer, sal_Int32 n) const; }; diff --git a/include/osl/process.h b/include/osl/process.h index 49fe59264059..3c58419420d0 100644 --- a/include/osl/process.h +++ b/include/osl/process.h @@ -101,43 +101,43 @@ typedef void* oslProcess; Executes the program image provided in strImageName in a new process. - @param ustrImageName - [in] The file URL of the executable to be started. + @param[in] ustrImageName + The file URL of the executable to be started. Can be NULL in this case the file URL of the executable must be the first element in ustrArguments. - @param ustrArguments - [in] An array of argument strings. Can be NULL if strImageName is not NULL. + @param[in] ustrArguments + An array of argument strings. Can be NULL if strImageName is not NULL. If strImageName is NULL it is expected that the first element contains the file URL of the executable to start. - @param nArguments - [in] The number of arguments provided. If this number is 0 strArguments will be ignored. + @param[in] nArguments + The number of arguments provided. If this number is 0 strArguments will be ignored. - @param Options - [in] A combination of int-constants to describe the mode of execution. + @param[in] Options + A combination of int-constants to describe the mode of execution. - @param Security - [in] The user and his rights for which the process is started. May be NULL in which case + @param[in] Security + The user and his rights for which the process is started. May be NULL in which case the process will be started in the context of the current user. - @param ustrDirectory - [in] The file URL of the working directory of the new process. If the specified directory + @param[in] ustrDirectory + The file URL of the working directory of the new process. If the specified directory does not exist or is inaccessible the working directory of the newly created process is undefined. If this parameter is NULL or the caller provides an empty string the new process will have the same current working directory as the calling process. - @param ustrEnvironments - [in] An array of strings describing environment variables that should be merged into the + @param[in] ustrEnvironments + An array of strings describing environment variables that should be merged into the environment of the new process. Each string has to be in the form "variable=value". This parameter can be NULL in which case the new process gets the same environment as the parent process. - @param nEnvironmentVars - [in] The number of environment variables to set. + @param[in] nEnvironmentVars + The number of environment variables to set. - @param pProcess - [out] Pointer to a oslProcess variable, which receives the handle of the newly created process. + @param[out] pProcess + Pointer to a oslProcess variable, which receives the handle of the newly created process. This parameter must not be NULL. @retval osl_Process_E_None on success @@ -164,57 +164,57 @@ SAL_DLLPUBLIC oslProcessError SAL_CALL osl_executeProcess( /** Execute a process and redirect child process standard IO. - @param strImageName - [in] The file URL of the executable to be started. + @param[in] strImageName + The file URL of the executable to be started. Can be NULL in this case the file URL of the executable must be the first element in ustrArguments. - @param ustrArguments - [in] An array of argument strings. Can be NULL if strImageName is not NULL. + @param[in] ustrArguments + An array of argument strings. Can be NULL if strImageName is not NULL. If strImageName is NULL it is expected that the first element contains the file URL of the executable to start. - @param nArguments - [in] The number of arguments provided. If this number is 0 strArguments will be ignored. + @param[in] nArguments + The number of arguments provided. If this number is 0 strArguments will be ignored. - @param Options - [in] A combination of int-constants to describe the mode of execution. + @param[in] Options + A combination of int-constants to describe the mode of execution. - @param Security - [in] The user and his rights for which the process is started. May be NULL in which case + @param[in] Security + The user and his rights for which the process is started. May be NULL in which case the process will be started in the context of the current user. - @param ustrDirectory - [in] The file URL of the working directory of the new process. If the specified directory + @param[in] ustrDirectory + The file URL of the working directory of the new process. If the specified directory does not exist or is inaccessible the working directory of the newly created process is undefined. If this parameter is NULL or the caller provides an empty string the new process will have the same current working directory as the calling process. - @param ustrEnvironments - [in] An array of strings describing environment variables that should be merged into the + @param[in] ustrEnvironments + An array of strings describing environment variables that should be merged into the environment of the new process. Each string has to be in the form "variable=value". This parameter can be NULL in which case the new process gets the same environment as the parent process. - @param nEnvironmentVars - [in] The number of environment variables to set. + @param[in] nEnvironmentVars + The number of environment variables to set. - @param pProcess - [out] Pointer to a oslProcess variable, which receives the handle of the newly created process. + @param[out] pProcess + Pointer to a oslProcess variable, which receives the handle of the newly created process. This parameter must not be NULL. - @param pChildInputWrite - [in] Pointer to a oslFileHandle variable that receives the handle which can be used to write + @param[in] pChildInputWrite + Pointer to a oslFileHandle variable that receives the handle which can be used to write to the child process standard input device. The returned handle is not random accessible. The handle has to be closed with osl_closeFile if no longer used. This parameter can be NULL. - @param pChildOutputRead - [in] Pointer to a oslFileHandle variable that receives the handle which can be used to read from + @param[in] pChildOutputRead + Pointer to a oslFileHandle variable that receives the handle which can be used to read from the child process standard output device. The returned handle is not random accessible. The Handle has to be closed with osl_closeFile if no longer used. This parameter can be NULL. - @param pChildErrorRead - [in] Pointer to a oslFileHandle variable that receives the handle which can be used to read from + @param[in] pChildErrorRead + Pointer to a oslFileHandle variable that receives the handle which can be used to read from the child process standard error device. The returned handle is not random accessible. The Handle has to be closed with osl_closeFile if no longer used. This parameter can be NULL. @@ -244,7 +244,8 @@ SAL_DLLPUBLIC oslProcessError SAL_CALL osl_executeProcess_WithRedirectedIO( oslFileHandle* pChildErrorRead); /** Terminate a process - @param Process [in] the handle of the process to be terminated + + @param[in] Process the handle of the process to be terminated @see osl_executeProcess @see osl_getProcess @@ -255,8 +256,10 @@ SAL_DLLPUBLIC oslProcessError SAL_CALL osl_terminateProcess( /** @deprecated + Retrieve the process handle of a process identifier - @param Ident [in] a process identifier + + @param[in] Ident a process identifier @return the process handle on success, NULL in all other cases */ @@ -265,15 +268,18 @@ SAL_DLLPUBLIC oslProcess SAL_CALL osl_getProcess( /** Free the specified process-handle. - @param Process [in] + + @param[in] Process */ SAL_DLLPUBLIC void SAL_CALL osl_freeProcessHandle( oslProcess Process); /** Wait for completion of the specified childprocess. - @param Process [in] + @param[in] Process + @retval ols_Process_E_None + @see osl_executeProcess */ SAL_DLLPUBLIC oslProcessError SAL_CALL osl_joinProcess( @@ -282,12 +288,9 @@ SAL_DLLPUBLIC oslProcessError SAL_CALL osl_joinProcess( /** Wait with a timeout for the completion of the specified child process. - @param Process [in] - A process identifier. - - @param pTimeout [in] - A timeout value or NULL for infinite waiting. - The unit of resolution is second. + @param[in] Process A process identifier. + @param[in] pTimeout A timeout value or NULL for infinite waiting. + The unit of resolution is second. @retval osl_Process_E_None on success @retval osl_Process_E_TimedOut waiting for the child process timed out @@ -318,7 +321,7 @@ SAL_DLLPUBLIC oslProcessError SAL_CALL osl_getProcessInfo( oslProcess Process, oslProcessData Fields, oslProcessInfo* pInfo); /** Get the filename of the executable. - @param strFile [out] the string that receives the executable file path. + @param[out] strFile the string that receives the executable file path. @return osl_Process_E_None or does not return. @see osl_executeProcess @@ -338,8 +341,8 @@ SAL_DLLPUBLIC oslProcessError SAL_CALL osl_getExecutableFile( SAL_DLLPUBLIC sal_uInt32 SAL_CALL osl_getCommandArgCount(void); /** Get the nArg-th command-line argument passed to the main-function of this process. - @param nArg [in] The number of the argument to return. - @param strCommandArg [out] The string receives the nArg-th command-line argument. + @param[in] nArg The number of the argument to return. + @param[out] strCommandArg The string receives the nArg-th command-line argument. @return osl_Process_E_None or does not return. @see osl_executeProcess */ @@ -353,8 +356,8 @@ SAL_DLLPUBLIC oslProcessError SAL_CALL osl_getCommandArg( be taken. This is due to Windows 9x/ME limitation that don't allow UTF-16 wmain to provide a osl_setCommandArgsU( int argc, sal_Unicode **argv ); - @param argc [in] The number of elements in the argv array. - @param argv [in] The array of command-line arguments. + @param[in] argc The number of elements in the argv array. + @param[in] argv The array of command-line arguments. @see osl_getExecutableFile @see osl_getCommandArgCount @see osl_getCommandArg @@ -362,15 +365,15 @@ SAL_DLLPUBLIC oslProcessError SAL_CALL osl_getCommandArg( SAL_DLLPUBLIC void SAL_CALL osl_setCommandArgs (int argc, char **argv); /** Get the value of one environment variable. - @param strVar [in] denotes the name of the variable to get. - @param strValue [out] string that receives the value of environment variable. + @param[in] strVar denotes the name of the variable to get. + @param[out] strValue string that receives the value of environment variable. */ SAL_DLLPUBLIC oslProcessError SAL_CALL osl_getEnvironment( rtl_uString *strVar, rtl_uString **strValue); /** Set the value of one environment variable. - @param strVar [in] denotes the name of the variable to set. - @param strValue [in] string of the new value of environment variable. + @param[in] strVar denotes the name of the variable to set. + @param[in] strValue string of the new value of environment variable. @since UDK 3.2.13 */ @@ -378,7 +381,7 @@ SAL_DLLPUBLIC oslProcessError SAL_CALL osl_setEnvironment( rtl_uString *strVar, rtl_uString *strValue); /** Unsets the value of one environment variable. - @param strVar [in] denotes the name of the variable to unset. + @param[in] strVar denotes the name of the variable to unset. @since UDK 3.2.13 */ @@ -388,7 +391,7 @@ SAL_DLLPUBLIC oslProcessError SAL_CALL osl_clearEnvironment( /** Get the working directory of the current process as a file URL. The file URL is encoded as common for the OSL file API. - @param pustrWorkingDir [out] string that receives the working directory file URL. + @param[out] pustrWorkingDir string that receives the working directory file URL. */ SAL_DLLPUBLIC oslProcessError SAL_CALL osl_getProcessWorkingDir( @@ -396,7 +399,7 @@ SAL_DLLPUBLIC oslProcessError SAL_CALL osl_getProcessWorkingDir( /** Get the locale the process is currently running in. - @param ppLocale [out] a pointer that receives the currently selected locale structure + @param[out] ppLocale a pointer that receives the currently selected locale structure */ SAL_DLLPUBLIC oslProcessError SAL_CALL osl_getProcessLocale( @@ -404,10 +407,10 @@ SAL_DLLPUBLIC oslProcessError SAL_CALL osl_getProcessLocale( /** Change the locale of the process. - @param pLocale [in] a pointer to the locale to be set + @param[in] pLocale a pointer to the locale to be set @deprecated LibreOffice itself does not use this, and client code should - not have good use for it either. It may eventually be removed. + not have good use for it either. It may eventually be removed. */ SAL_DLLPUBLIC oslProcessError SAL_CALL osl_setProcessLocale( diff --git a/include/osl/profile.h b/include/osl/profile.h index e8584ec85b85..fad2670b173e 100644 --- a/include/osl/profile.h +++ b/include/osl/profile.h @@ -57,10 +57,10 @@ SAL_DLLPUBLIC oslProfile SAL_CALL osl_openProfile( SAL_DLLPUBLIC sal_Bool SAL_CALL osl_closeProfile( oslProfile Profile) SAL_COLD; - /** Deprecated API. @deprecated */ + SAL_DLLPUBLIC sal_Bool SAL_CALL osl_flushProfile( oslProfile Profile) SAL_COLD; /** Deprecated API. @@ -94,6 +94,7 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_writeProfileString( oslProfile Profile, const sal_Char* pszSection, const sal_Char* pszEntry, const sal_Char* pszString) SAL_COLD; + /** Deprecated API. @deprecated */ @@ -101,6 +102,7 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_writeProfileBool( oslProfile Profile, const sal_Char* pszSection, const sal_Char* pszEntry, sal_Bool Value) SAL_COLD; + /** Deprecated API. @deprecated */ diff --git a/include/osl/security_decl.hxx b/include/osl/security_decl.hxx index e7443439ca95..b9b41677a38d 100644 --- a/include/osl/security_decl.hxx +++ b/include/osl/security_decl.hxx @@ -21,7 +21,7 @@ #define INCLUDED_OSL_SECURITY_DECL_HXX #include -# include +#include namespace osl { @@ -42,8 +42,10 @@ public: /** get the security information for one user. The underlying operating system is asked for this information. + @param[in] strName denotes the name of the user @param[in] strPasswd denotes the password of this user + @retval True, if the specified user is known by the underlying operating system @retval False unknown user */ @@ -64,7 +66,7 @@ public: @param[in] strFileServer denotes the file server to login to @retval True if the specified user is known by the file server and they - could be connected + could be connected @retval False if the user is not known by the file server */ inline bool SAL_CALL logonUser(const rtl::OUString & strName, @@ -72,6 +74,7 @@ public: const rtl::OUString & strFileServer); /** get the ident of the logged in user. + @param[out] strIdent is the OUString which returns the name @retval True if any user is successfully logged in @@ -80,6 +83,7 @@ public: inline bool SAL_CALL getUserIdent( rtl::OUString& strIdent) const; /** get the name of the logged in user. + @param[out] strName is the OUString which returns the name @param[in] bIncludeDomain Include the Domain name (like "ORG\username"). Affects Windows only. This parameter is available since LibreOffice 5.2. @@ -98,6 +102,7 @@ public: inline bool SAL_CALL getHomeDir( rtl::OUString& strDirectory) const; /** get the directory for configuration data of the logged in user. + @param[out] strDirectory is the OUString which returns the directory name @retval True if any user is successfully logged in @@ -106,6 +111,7 @@ public: inline bool SAL_CALL getConfigDir( rtl::OUString & strDirectory) const; /** Query if the user who is logged in has administrator rights. + @retval True if the user has administrator rights @retval False if the user does not have admin rights */ @@ -114,7 +120,6 @@ public: /** Returns the underlying oslSecurity handle */ inline oslSecurity getHandle() const; - }; } diff --git a/include/osl/signal.h b/include/osl/signal.h index a2efece30d05..a4a5cb0caa80 100644 --- a/include/osl/signal.h +++ b/include/osl/signal.h @@ -73,7 +73,7 @@ typedef struct # pragma pack(pop) #endif -/** the function-ptr. representing the signal handler-function. +/** The function-ptr representing the signal handler-function. */ typedef oslSignalAction (SAL_CALL *oslSignalHandlerFunction)(void* pData, oslSignalInfo* pInfo); @@ -90,8 +90,7 @@ SAL_DLLPUBLIC oslSignalAction SAL_CALL osl_raiseSignal( On default error reporting is enabled after process startup. - @param bEnable [in] - Enables or disables error reporting. + @param[in] bEnable Enables or disables error reporting. @retval sal_True if previous state of error reporting was enabled @retval sal_False if previous state of error reporting was disabled diff --git a/include/osl/socket.h b/include/osl/socket.h index 3e868b7df0c1..2ec3890b3776 100644 --- a/include/osl/socket.h +++ b/include/osl/socket.h @@ -62,7 +62,6 @@ typedef enum { osl_Socket_Protocol_FORCE_EQUAL_SIZE = SAL_MAX_ENUM } oslProtocol; - /** Represents the type of a socket */ @@ -242,8 +241,8 @@ SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_createInetBroadcastAddr ( /** Create an internet-address, consisting of host address and port. We interpret strDottedAddr as a dotted-decimal inet-addr (e.g. "141.99.128.50"). - @param strDottedAddr [in] String with dotted address. - @param Port [in] portnumber in host byte order. + @param[in] strDottedAddr String with dotted address. + @param[in] Port portnumber in host byte order. @retval 0 if address could not be created. */ SAL_DLLPUBLIC oslSocketAddr SAL_CALL osl_createInetSocketAddr ( @@ -554,11 +553,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: -
  • osl_Socket_MsgNormal -
  • osl_Socket_MsgOOB -
  • osl_Socket_MsgPeek -
  • osl_Socket_MsgDontRoute -
  • osl_Socket_MsgMaxIOVLen + @li osl_Socket_MsgNormal + @li osl_Socket_MsgOOB + @li osl_Socket_MsgPeek + @li osl_Socket_MsgDontRoute + @li osl_Socket_MsgMaxIOVLen @return the number of transferred bytes. */ @@ -582,12 +581,15 @@ SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_sendSocket( @param[in] pBuffer Points to a buffer that contains the send-data. @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: -
  • osl_Socket_MsgNormal -
  • osl_Socket_MsgOOB -
  • osl_Socket_MsgPeek -
  • osl_Socket_MsgDontRoute -
  • osl_Socket_MsgMaxIOVLen + @param[in] Flag + @parblock + Modifier for the call. Valid values are: + @li osl_Socket_MsgNormal + @li osl_Socket_MsgOOB + @li osl_Socket_MsgPeek + @li osl_Socket_MsgDontRoute + @li osl_Socket_MsgMaxIOVLen + @endparblock @return the number of transferred bytes. */ @@ -603,12 +605,12 @@ 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. - @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. + + @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. */ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isReceiveReady( oslSocket Socket, const TimeValue* pTimeout); @@ -616,13 +618,14 @@ 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. - @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 - the time define by timeout value. + the time define by timeout value. + + @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. */ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isSendReady( oslSocket Socket, const TimeValue* pTimeout); @@ -630,112 +633,83 @@ 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. - @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. + + @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. */ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isExceptionPending( oslSocket Socket, const TimeValue* pTimeout); /** Shuts down communication on a connected socket. @param[in] Socket the Socket to perfom the operation on. - @param[in] Direction denotes which end of the socket - should be closed: -
      -
    • osl_Socket_DirRead closes read operations. -
    • osl_Socket_DirReadWrite closes write operations. -
    • osl_Socket_DirWrite closes read and write operations. -
    - @return sal_True if the socket could be closed down. + @param[in] + @parblock + Direction denotes which end of the socket should be closed: + @li osl_Socket_DirRead - closes read operations. + @li osl_Socket_DirReadWrite - closes write operations. + @li osl_Socket_DirWrite - closes read and write operations. + @endparblock + + @retval sal_True if the socket could be closed down. */ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_shutdownSocket(oslSocket Socket, oslSocketDirection Direction); /** Retrieves attributes associated with the socket. - @param Socket is the socket to query. - - @param Level selects the level for which an option should be queried. - Valid values are: -
      -
    • osl_sol_socket: Socket Level -
    • osl_sol_tcp: Level of Transmission Control Protocol -
    - - @param Option denotes the option to query. - Valid values (depending on the Level) are: -
      -
    • osl_Socket_Option_Debug
      - (sal_Bool) Socket debug flag 1 = enabled, 0 = disabled. - -
    • osl_Socket_OptionAcceptConn
      -
    • osl_Socket_OptionReuseAddr
      - (sal_Bool) Allows the socket to be bound to an address that is - already in use. - 1 = multiple bound allowed, 0 = no multiple bounds allowed - -
    • osl_Socket_OptionKeepAlive
      - (sal_Bool) Keepalive packets are sent by the underlying socket. - 1 = enabled, 0 = disabled - -
    • osl_Socket_OptionDontRoute
      - (sal_Bool) Do not route: send directly to interface. - 1 = do not route , 0 = routing possible - -
    • osl_Socket_OptionBroadcast
      - (sal_Bool) Transmission of broadcast messages are allowed on the socket. - 1 = transmission allowed, 0 = transmission disallowed - -
    • osl_Socket_OptionUseLoopback
      - -
    • osl_Socket_OptionLinger
      - (sal_Int32) Linger on close if unsent data is present. - 0 = linger is off, > 0 = timeout in seconds. - -
    • osl_Socket_OptionOOBinLine
      - - -
    • osl_Socket_OptionSndBuf
      - (sal_Int32) Size of the send buffer in bytes. Data is sent after - SndTimeo or when the buffer is full. This allows faster writing - to the socket. - -
    • osl_Socket_OptionRcvBuf
      - (sal_Int32) Size of the receive buffer in bytes. Data is sent after - SndTimeo or when the buffer is full. This allows faster writing - to the socket and larger packet sizes. - -
    • osl_Socket_OptionSndLowat
      - -
    • osl_Socket_OptionRcvLowat
      - -
    • osl_Socket_OptionSndTimeo
      - (sal_Int32) Data is sent after this timeout. This allows gathering - of data to send larger packages but increases latency times. - -
    • osl_Socket_OptionRcvTimeo
      - -
    • osl_Socket_OptionError
      -
    • osl_Socket_OptionType
      - -
    • osl_Socket_OptionTcpNoDelay
      - Disables the Nagle algorithm for send coalescing. (Do not - collect data until a packet is full, instead send immediately. - This increases network traffic but might improve latency-times.) - 1 = disables the algorithm, 0 = keeps it enabled. -
    - If not above mentioned otherwise, the options are only valid for - level osl_Socket_LevelSocket. - - @param pBuffer Pointer to a buffer large enough to take the desired - attribute-value. + @param Socket is the socket to query. + @param Level + @parblock + Selects the level for which an option should be queried. + Valid values are: + @li osl_sol_socket - Socket Level + @li osl_sol_tcp - Level of Transmission Control Protocol + @endparblock + + @param Option + @parblock + Denotes the option to query. Valid values (depending on the Level) are: + @li osl_Socket_Option_Debug - (sal_Bool) Socket debug flag 1 = enabled, 0 = disabled. + @li osl_Socket_OptionAcceptConn + @li osl_Socket_OptionReuseAddr - (sal_Bool) Allows the socket to be bound to an address that is + already in use. 1 = multiple bound allowed, 0 = no multiple bounds allowed + @li osl_Socket_OptionKeepAlive (sal_Bool) Keepalive packets are sent by the underlying socket. + 1 = enabled, 0 = disabled + @li osl_Socket_OptionDontRoute - (sal_Bool) Do not route: send directly to interface. + 1 = do not route , 0 = routing possible + @li osl_Socket_OptionBroadcast - (sal_Bool) Transmission of broadcast messages are allowed on the socket. + 1 = transmission allowed, 0 = transmission disallowed + @li osl_Socket_OptionUseLoopback + @li osl_Socket_OptionLinger (sal_Int32) Linger on close if unsent data is present. + 0 = linger is off, > 0 = timeout in seconds. + @li osl_Socket_OptionOOBinLine + @li osl_Socket_OptionSndBuf (sal_Int32) Size of the send buffer in bytes. Data is sent after + SndTimeo or when the buffer is full. This allows faster writing to the socket. + @li osl_Socket_OptionRcvBuf (sal_Int32) Size of the receive buffer in bytes. Data is sent after + SndTimeo or when the buffer is full. This allows faster writing to the socket and larger packet sizes. + @li osl_Socket_OptionSndLowat + @li osl_Socket_OptionRcvLowat + @li osl_Socket_OptionSndTimeo (sal_Int32) Data is sent after this timeout. This allows gathering + of data to send larger packages but increases latency times. + @li osl_Socket_OptionRcvTimeo + @li osl_Socket_OptionError + @li osl_Socket_OptionType + @li osl_Socket_OptionTcpNoDelay Disables the Nagle algorithm for send coalescing. (Do not + collect data until a packet is full, instead send immediately. This increases network traffic + but might improve latency-times.) + 1 = disables the algorithm, 0 = keeps it enabled. + + If not above mentioned otherwise, the options are only valid for level osl_Socket_LevelSocket. + @endparblock + @param pBuffer Pointer to a buffer large enough to take the desired attribute-value. @param BufferLen contains the length of the Buffer. - @return -1 if an error occurred or else the size of the data copied into - pBuffer. + @return -1 if an error occurred or else the size of the data copied into pBuffer. + @see osl_setSocketOption() */ SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_getSocketOption( oslSocket Socket, @@ -747,19 +721,16 @@ SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_getSocketOption( oslSocket Socket, /** Sets the sockets attributes. @param Socket is the socket to modify. - - @param Level selects the level for which an option should be changed. - Valid values are: -
      -
    • osl_sol_socket: Socket Level -
    • osl_sol_tcp: Level of Transmission Control Protocol -
    - + @param Level + @parblock + selects the level for which an option should be changed. + Valid values are: + @li osl_sol_socket - Socket Level + @li osl_sol_tcp - Level of Transmission Control Protocol + @endparblock @param Option denotes the option to modify. See osl_setSocketOption() for more - details. - + details. @param pBuffer Pointer to a Buffer which contains the attribute-value. - @param BufferLen contains the length of the Buffer. @retval True if the option could be changed. @@ -771,9 +742,10 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_setSocketOption( oslSocket Socket, sal_uInt32 BufferLen); /** 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. + @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( @@ -781,15 +753,18 @@ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_enableNonBlockingMode( /** Query state of non-blocking-mode of the socket. + @param Socket Query mode for this socket. + @retval True if non-blocking-mode is enabled. */ SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isNonBlockingMode( oslSocket Socket); - /** Queries the socket for its type. + @param[in] Socket The socket to query. + @retval osl_Socket_TypeStream @retval osl_Socket_TypeDgram @retval osl_Socket_TypeRaw @@ -801,13 +776,15 @@ SAL_DLLPUBLIC oslSocketType SAL_CALL osl_getSocketType( oslSocket Socket); /** returns a string which describes the last socket error. + @param[in] Socket The socket to query. @param[out] strError The string that receives the error message. */ SAL_DLLPUBLIC void SAL_CALL osl_getLastSocketErrorDescription( oslSocket Socket, rtl_uString **strError); -/** returns a constant describing the last error for the socket system. +/** Returns a constant describing the last error for the socket system. + @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. @@ -820,53 +797,58 @@ SAL_DLLPUBLIC oslSocketError SAL_CALL osl_getLastSocketError( typedef struct oslSocketSetImpl * oslSocketSet; /** Creates a set of sockets to be used with osl_demultiplexSocketEvents(). + @return A oslSocketSet or 0 if creation failed. */ SAL_DLLPUBLIC oslSocketSet SAL_CALL osl_createSocketSet(void); -/** Destroys a oslSocketSet. +/** Destroys an oslSocketSet. */ SAL_DLLPUBLIC void SAL_CALL osl_destroySocketSet(oslSocketSet Set); /** Clears the set from all previously added sockets. + @param Set the set to be cleared. */ SAL_DLLPUBLIC void SAL_CALL osl_clearSocketSet(oslSocketSet Set); /** Adds a socket to the set. + @param Set the set were the socket is added. @param Socket the socket to be added. */ SAL_DLLPUBLIC void SAL_CALL osl_addToSocketSet(oslSocketSet Set, oslSocket Socket); /** Removes a socket from the set. + @param Set the set were the socket is removed from. @param Socket the socket to be removed. */ SAL_DLLPUBLIC void SAL_CALL osl_removeFromSocketSet(oslSocketSet Set, oslSocket Socket); /** Checks if socket is in the set. + @param Set the set to be checked. @param Socket check if this 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); /** Checks multiple sockets for events. - @param IncomingSet Checks the sockets in this set - for incoming events (read, accept). If the set is 0, - it is just skipped. - @param OutgoingSet Checks the sockets in this set - for outgoing events (write, connect). If the set is 0, - it is just skipped. - @param OutOfBandSet Checks the sockets in this set - for out-of-band events. If the set is 0, it is just skipped. - @param pTimeout Address of the number of milliseconds to wait for events. If - *pTimeout is -1, the call will block until an event or an error - occurs. - @return -1 on errors, otherwise the number of sockets with - pending events. In case of timeout, the number might be 0. + + @param IncomingSet Checks the sockets in this set for incoming events (read, accept). If the set is 0, + it is just skipped. + @param OutgoingSet Checks the sockets in this set for outgoing events (write, connect). If the set is 0, + it is just skipped. + @param OutOfBandSet Checks the sockets in this set for out-of-band events. If the set is 0, it is just + skipped. + @param pTimeout Address of the number of milliseconds to wait for events. If *pTimeout is -1, the call + will block until an event or an error occurs. + + @return -1 on errors, otherwise the number of sockets with pending events. In case of timeout, the + number might be 0. */ SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_demultiplexSocketEvents(oslSocketSet IncomingSet, oslSocketSet OutgoingSet, @@ -874,6 +856,7 @@ SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_demultiplexSocketEvents(oslSocketSet Incomi const TimeValue* pTimeout); /** Closes the socket terminating any ongoing dataflow. + @param[in] Socket The socket to close. */ SAL_DLLPUBLIC void SAL_CALL osl_closeSocket(oslSocket Socket); @@ -881,31 +864,33 @@ SAL_DLLPUBLIC void SAL_CALL osl_closeSocket(oslSocket Socket); /** Retrieves n bytes from the stream and copies them into pBuffer. The function avoids incomplete reads due to packet boundaries. + @param[in] Socket The socket to read from. @param[out] pBuffer receives the read data. @param[out] nSize the number of bytes to read. pBuffer must be large enough - to hold the n bytes! + to hold the n bytes! + @return the number of read bytes. The number will only be smaller than - n if an exceptional condition (e.g. connection closed) occurs. + n if an exceptional condition (e.g. connection closed) occurs. */ SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_readSocket( oslSocket Socket, void *pBuffer, sal_Int32 nSize ); /** Writes n bytes from pBuffer to the stream. The method avoids incomplete writes due to packet boundaries. + @param[out] Socket The socket to write to. @param[in] pBuffer contains the data to be written. @param[in] nSize the number of bytes to write. + @return the number of written bytes. The number will only be smaller than - nSize if an exceptional condition (e.g. connection closed) occurs. + nSize if an exceptional condition (e.g. connection closed) occurs. */ SAL_DLLPUBLIC sal_Int32 SAL_CALL osl_writeSocket( oslSocket Socket, const void *pBuffer, sal_Int32 nSize ); /**@} end section oslSocket */ - - #ifdef __cplusplus } #endif diff --git a/include/osl/socket_decl.hxx b/include/osl/socket_decl.hxx index 2cad281a2748..2c9020e3e93d 100644 --- a/include/osl/socket_decl.hxx +++ b/include/osl/socket_decl.hxx @@ -314,15 +314,13 @@ namespace osl /** Queries the socket for its type. - @return one of: -
      -
    • osl_Socket_TypeStream -
    • osl_Socket_TypeDgram -
    • osl_Socket_TypeRaw -
    • osl_Socket_TypeRdm -
    • osl_Socket_TypeSeqPacket -
    • osl_invalid_SocketType, if an error occurred -
    + + @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 */ inline oslSocketType SAL_CALL getType() const; diff --git a/include/osl/thread.hxx b/include/osl/thread.hxx index 3adfc83fe295..389739c70aa7 100644 --- a/include/osl/thread.hxx +++ b/include/osl/thread.hxx @@ -34,7 +34,7 @@ namespace osl /** threadFunc is the function which is executed by the threads created by the osl::Thread class. The function's signature matches the one of oslWorkerFunction which is declared in - osl/thread.h . + osl/thread.h */ extern "C" inline void SAL_CALL threadFunc( void* param); diff --git a/include/osl/time.h b/include/osl/time.h index 6755dba210d4..4843a9d02e25 100644 --- a/include/osl/time.h +++ b/include/osl/time.h @@ -84,7 +84,7 @@ extern "C" { typedef struct _oslDateTime { - /** contains the nanoseconds . + /** contains the nanoseconds */ sal_uInt32 NanoSeconds; -- cgit v1.2.3