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