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
  39     /** Does not create a pipe. Use assignment operator to
  40         make this a usable pipe.
  41     */
  42     inline Pipe();
  43
  44     /** Creates an insecure pipe that is accessible for all users.
  45         @param strName
  46         @param Options
  47     */
  48     inline Pipe(const ::rtl::OUString& strName, oslPipeOptions Options);
  49
  50     /** Creates a secure pipe that access depends on the umask settings.
  51         @param strName
  52         @param Options
  53         @param rSecurity
  54     */
  55     inline Pipe(const ::rtl::OUString& strName, oslPipeOptions Options,const Security & rSecurity);
  56
  57     /** Copy constructor.
  58     */
  59     inline Pipe(const Pipe& pipe);
  60
  61 #if defined LIBO_INTERNAL_ONLY
  62     inline Pipe(Pipe && other) noexcept;
  63 #endif
  64
  65     /** Constructs a Pipe reference without acquiring the handle
  66     */
  67     inline Pipe( oslPipe pipe, __sal_NoAcquire noacquire );
  68
  69     /** Creates pipe as wrapper around the underlying oslPipe.
  70         @param Pipe
  71     */
  72     inline Pipe(oslPipe Pipe);
  73
  74     /** Destructor. Destroys the underlying oslPipe.
  75     */
  76     inline ~Pipe();
  77
  78     inline bool SAL_CALL is() const;
  79
  80     /** Creates an insecure pipe that is accessible for all users
  81         with the given attributes.
  82         If the pipe was already created, the old one will be discarded.
  83         @param strName
  84         @param Options
  85         @param rSec
  86         @return True if socket was successfully created.
  87     */
  88     inline bool create( const ::rtl::OUString & strName,
  89                             oslPipeOptions Options, const Security &rSec );
  90
  91     /** Creates a secure that access rights depend on the umask settings
  92         with the given attributes.
  93
  94         If socket was already created, the old one will be discarded.
  95         @param strName
  96         @param Options
  97         @return True if socket was successfully created.
  98     */
  99     inline bool create( const ::rtl::OUString & strName, oslPipeOptions Options = osl_Pipe_OPEN );
 100
 101     /** releases the underlying handle
 102      */
 103     inline void SAL_CALL clear();
 104
 105     /** Assignment operator. If pipe was already created, the old one will
 106         be discarded.
 107     */
 108     inline Pipe& SAL_CALL operator= (const Pipe& pipe);
 109
 110 #if defined LIBO_INTERNAL_ONLY
 111     inline Pipe & operator =(Pipe && other) noexcept;
 112 #endif
 113
 114     /** Assignment operator. If pipe was already created, the old one will
 115         be discarded.
 116     */
 117     inline Pipe& SAL_CALL operator= (const oslPipe pipe );
 118
 119     /** Checks if the pipe is valid.
 120         @return True if the object represents a valid pipe.
 121     */
 122     inline bool SAL_CALL isValid() const;
 123
 124     inline bool SAL_CALL operator==( const Pipe& rPipe ) const;
 125
 126     /** Closes the pipe.
 127     */
 128     inline void SAL_CALL close();
 129
 130     /** Accept connection on an existing pipe
 131     */
 132     inline oslPipeError SAL_CALL accept(StreamPipe& Connection);
 133
 134
 135     /** Delivers a constant describing the last error for the pipe system.
 136         @return ENONE if no error occurred, invalid_PipeError if
 137         an unknown (unmapped) error occurred, otherwise an enum describing the
 138         error.
 139     */
 140     inline oslPipeError SAL_CALL getError() const;
 141
 142     inline oslPipe SAL_CALL getHandle() const;
 143 };
 144
 145 /** A pipe to send or receive a stream of data.
 146 */
 147 class StreamPipe : public Pipe
 148 {
 149 public:
 150
 151     /** Creates an unattached pipe. You must attach the pipe to an oslPipe
 152         e.g. by using the operator=(oslPipe), before you can use the stream-
 153         functionality of the object.
 154     */
 155     inline StreamPipe();
 156
 157     /** Creates pipe as wrapper around the underlying oslPipe.
 158
 159         @param Pipe
 160     */
 161     inline StreamPipe(oslPipe Pipe);
 162
 163     /** Creates a pipe.
 164
 165         @param[in] strName Pipe name
 166         @param[in] Options Pipe options
 167     */
 168     inline StreamPipe(const ::rtl::OUString& strName, oslPipeOptions Options = osl_Pipe_OPEN);
 169
 170     /** Creates a pipe.
 171
 172         @param[in] strName Pipe name
 173         @param[in] Options Pipe options
 174         @param[in] rSec    Security for the pipe
 175     */
 176     inline StreamPipe(const ::rtl::OUString& strName, oslPipeOptions Options, const Security &rSec );
 177
 178     /** Constructs a Pipe reference without acquiring the handle
 179     */
 180     inline StreamPipe( oslPipe pipe, __sal_NoAcquire noacquire );
 181
 182     /** Attaches the oslPipe to this object. If the object
 183         already was attached to an oslPipe, the old one will
 184         be closed and destroyed.
 185
 186         @param[in] Pipe    Pipe to attach to this object
 187     */
 188     inline StreamPipe & SAL_CALL operator=(oslPipe Pipe);
 189
 190     /** Assignment operator
 191     */
 192     inline StreamPipe& SAL_CALL operator=(const Pipe& pipe);
 193
 194     /** Tries to receives BytesToRead data from the connected pipe,
 195
 196         @param[out] pBuffer Points to a buffer that will be filled with the received
 197                      data.
 198         @param[in] BytesToRead The number of bytes to read. pBuffer must have at least
 199                      this size.
 200
 201         @return the number of received bytes.
 202     */
 203     inline sal_Int32 SAL_CALL recv(void* pBuffer, sal_Int32 BytesToRead) const;
 204
 205     /** Tries to sends BytesToSend data from the connected pipe.
 206
 207         @param[in] pBuffer Points to a buffer that contains the send-data.
 208         @param[in] BytesToSend The number of bytes to send. pBuffer must have at least
 209                        this size.
 210
 211         @return the number of transferred bytes.
 212     */
 213     inline sal_Int32 SAL_CALL send(const void* pBuffer, sal_Int32 BytesToSend) const;
 214
 215     /** Retrieves n bytes from the stream and copies them into pBuffer.
 216         The method avoids incomplete reads due to packet boundaries.
 217
 218         @param[in] pBuffer receives the read data.
 219         @param[in] n the number of bytes to read. pBuffer must be large enough
 220         to hold the n bytes!
 221
 222         @return the number of read bytes. The number will only be smaller than
 223             n if an exceptional condition (e.g. connection closed) occurs.
 224     */
 225     inline sal_Int32 SAL_CALL read(void* pBuffer, sal_Int32 n) const;
 226
 227     /** Writes n bytes from pBuffer to the stream. The method avoids
 228         incomplete writes due to packet boundaries.
 229
 230         @param[in] pBuffer contains the data to be written.
 231         @param[in] n the number of bytes to write.
 232
 233         @return the number of written bytes. The number will only be smaller than
 234             n if an exceptional condition (e.g. connection closed) occurs.
 235     */
 236     sal_Int32 SAL_CALL write(const void* pBuffer, sal_Int32 n) const;
 237 };
 238
 239 }
 240 #endif
 241
 242 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */