include/osl/pipe_decl.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #ifndef INCLUDED_OSL_PIPE_DECL_HXX
  20 #define INCLUDED_OSL_PIPE_DECL_HXX
  21
  22 #include "osl/pipe.h"
  23 #include "osl/security.hxx"
  24 #include "rtl/ustring.hxx"
  25
  26 namespace osl
  27 {
  28 class StreamPipe;
  29
  30 /** Represents a pipe.
  31 */
  32 class Pipe
  33 {
  34 protected:
  35     oslPipe m_handle;
  36
  37 public:
  38     /** Does not create a pipe. Use assignment operator to
  39         make this a usable pipe.
  40     */
  41     inline Pipe();
  42
  43     /** Creates an insecure pipe that is accessible for all users.
  44         @param strName
  45         @param Options
  46     */
  47     inline Pipe(const ::rtl::OUString& strName, oslPipeOptions Options);
  48
  49     /** Creates a secure pipe that access depends on the umask settings.
  50         @param strName
  51         @param Options
  52         @param rSecurity
  53     */
  54     inline Pipe(const ::rtl::OUString& strName, oslPipeOptions Options, const Security& rSecurity);
  55
  56     /** Copy constructor.
  57     */
  58     inline Pipe(const Pipe& pipe);
  59
  60 #if defined LIBO_INTERNAL_ONLY
  61     inline Pipe(Pipe&& other) noexcept;
  62 #endif
  63
  64     /** Constructs a Pipe reference without acquiring the handle
  65     */
  66     inline Pipe(oslPipe pipe, __sal_NoAcquire noacquire);
  67
  68     /** Creates pipe as wrapper around the underlying oslPipe.
  69         @param Pipe
  70     */
  71     inline Pipe(oslPipe Pipe);
  72
  73     /** Destructor. Destroys the underlying oslPipe.
  74     */
  75     inline ~Pipe();
  76
  77     inline bool SAL_CALL is() const;
  78
  79     /** Creates an insecure pipe that is accessible for all users
  80         with the given attributes.
  81         If the pipe was already created, the old one will be discarded.
  82         @param strName
  83         @param Options
  84         @param rSec
  85         @return True if socket was successfully created.
  86     */
  87     inline bool create(const ::rtl::OUString& strName, oslPipeOptions Options,
  88                        const Security& rSec);
  89
  90     /** Creates a secure that access rights depend on the umask settings
  91         with the given attributes.
  92
  93         If socket was already created, the old one will be discarded.
  94         @param strName
  95         @param Options
  96         @return True if socket was successfully created.
  97     */
  98     inline bool create(const ::rtl::OUString& strName, oslPipeOptions Options = osl_Pipe_OPEN);
  99
 100     /** releases the underlying handle
 101      */
 102     inline void SAL_CALL clear();
 103
 104     /** Assignment operator. If pipe was already created, the old one will
 105         be discarded.
 106     */
 107     inline Pipe& SAL_CALL operator=(const Pipe& pipe);
 108
 109 #if defined LIBO_INTERNAL_ONLY
 110     inline Pipe& operator=(Pipe&& other) noexcept;
 111 #endif
 112
 113     /** Assignment operator. If pipe was already created, the old one will
 114         be discarded.
 115     */
 116     inline Pipe& SAL_CALL operator=(const oslPipe pipe);
 117
 118     /** Checks if the pipe is valid.
 119         @return True if the object represents a valid pipe.
 120     */
 121     inline bool SAL_CALL isValid() const;
 122
 123     inline bool SAL_CALL operator==(const Pipe& rPipe) const;
 124
 125     /** Closes the pipe.
 126     */
 127     inline void SAL_CALL close();
 128
 129     /** Accept connection on an existing pipe
 130     */
 131     inline oslPipeError SAL_CALL accept(StreamPipe& Connection);
 132
 133     /** Delivers a constant describing the last error for the pipe system.
 134         @return ENONE if no error occurred, invalid_PipeError if
 135         an unknown (unmapped) error occurred, otherwise an enum describing the
 136         error.
 137     */
 138     inline oslPipeError SAL_CALL getError() const;
 139
 140     inline oslPipe SAL_CALL getHandle() const;
 141 };
 142
 143 /** A pipe to send or receive a stream of data.
 144 */
 145 class StreamPipe : public Pipe
 146 {
 147 public:
 148     /** Creates an unattached pipe. You must attach the pipe to an oslPipe
 149         e.g. by using the operator=(oslPipe), before you can use the stream-
 150         functionality of the object.
 151     */
 152     inline StreamPipe();
 153
 154     /** Creates pipe as wrapper around the underlying oslPipe.
 155
 156         @param Pipe
 157     */
 158     inline StreamPipe(oslPipe Pipe);
 159
 160     /** Creates a pipe.
 161
 162         @param[in] strName Pipe name
 163         @param[in] Options Pipe options
 164     */
 165     inline StreamPipe(const ::rtl::OUString& strName, oslPipeOptions Options = osl_Pipe_OPEN);
 166
 167     /** Creates a pipe.
 168
 169         @param[in] strName Pipe name
 170         @param[in] Options Pipe options
 171         @param[in] rSec    Security for the pipe
 172     */
 173     inline StreamPipe(const ::rtl::OUString& strName, oslPipeOptions Options, const Security& rSec);
 174
 175     /** Constructs a Pipe reference without acquiring the handle
 176     */
 177     inline StreamPipe(oslPipe pipe, __sal_NoAcquire noacquire);
 178
 179     /** Attaches the oslPipe to this object. If the object
 180         already was attached to an oslPipe, the old one will
 181         be closed and destroyed.
 182
 183         @param[in] Pipe    Pipe to attach to this object
 184     */
 185     inline StreamPipe& SAL_CALL operator=(oslPipe Pipe);
 186
 187     /** Assignment operator
 188     */
 189     inline StreamPipe& SAL_CALL operator=(const Pipe& pipe);
 190
 191     /** Tries to receives BytesToRead data from the connected pipe,
 192
 193         @param[out] pBuffer Points to a buffer that will be filled with the received
 194                      data.
 195         @param[in] BytesToRead The number of bytes to read. pBuffer must have at least
 196                      this size.
 197
 198         @return the number of received bytes.
 199     */
 200     inline sal_Int32 SAL_CALL recv(void* pBuffer, sal_Int32 BytesToRead) const;
 201
 202     /** Tries to sends BytesToSend data from the connected pipe.
 203
 204         @param[in] pBuffer Points to a buffer that contains the send-data.
 205         @param[in] BytesToSend The number of bytes to send. pBuffer must have at least
 206                        this size.
 207
 208         @return the number of transferred bytes.
 209     */
 210     inline sal_Int32 SAL_CALL send(const void* pBuffer, sal_Int32 BytesToSend) const;
 211
 212     /** Retrieves n bytes from the stream and copies them into pBuffer.
 213         The method avoids incomplete reads due to packet boundaries.
 214
 215         @param[in] pBuffer receives the read data.
 216         @param[in] n the number of bytes to read. pBuffer must be large enough
 217         to hold the n bytes!
 218
 219         @return the number of read bytes. The number will only be smaller than
 220             n if an exceptional condition (e.g. connection closed) occurs.
 221     */
 222     inline sal_Int32 SAL_CALL read(void* pBuffer, sal_Int32 n) const;
 223
 224     /** Writes n bytes from pBuffer to the stream. The method avoids
 225         incomplete writes due to packet boundaries.
 226
 227         @param[in] pBuffer contains the data to be written.
 228         @param[in] n the number of bytes to write.
 229
 230         @return the number of written bytes. The number will only be smaller than
 231             n if an exceptional condition (e.g. connection closed) occurs.
 232     */
 233     sal_Int32 SAL_CALL write(const void* pBuffer, sal_Int32 n) const;
 234 };
 235 }
 236 #endif
 237
 238 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */