summaryrefslogtreecommitdiff
path: root/ace/FIFO_Recv_Msg.h
blob: b1c7afe3eb362e48fc817fe76cacb9afb8febfee (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
// -*- C++ -*-

//=============================================================================
/**
 *  @file    FIFO_Recv_Msg.h
 *
 *  $Id$
 *
 *  @author Doug Schmidt
 */
//=============================================================================


#ifndef ACE_FIFO_RECV_MSG_H
#define ACE_FIFO_RECV_MSG_H
#include /**/ "ace/pre.h"

#include "ace/FIFO_Recv.h"

#if !defined (ACE_LACKS_PRAGMA_ONCE)
# pragma once
#endif /* ACE_LACKS_PRAGMA_ONCE */

ACE_BEGIN_VERSIONED_NAMESPACE_DECL

// Forward decls
class ACE_Str_Buf;

/**
 * @class ACE_FIFO_Recv_Msg
 *
 * @brief Receiver side for the record oriented C++ wrapper for UNIX FIFOs.
 *
 * This method works slightly differently on platforms with the
 * @c ACE_HAS_STREAM_PIPES configuration setting than those without.
 * With ACE_HAS_STREAM_PIPES, the @c getmsg() system function is used
 * and it preserves message boundaries internally. Without
 * @c ACE_HAS_STREAM_PIPES, the message boundaries are emulated by
 * this class and ACE_FIFO_Send_Msg cooperating. The sending class
 * first writes an integer number of bytes in the message, then the
 * message. ACE_FIFO_Recv_Msg reads the count, then the data.
 * The operational differences occur primarily when a message is larger
 * than what a caller of this class requests. See recv() for details.
 */
class ACE_Export ACE_FIFO_Recv_Msg : public ACE_FIFO_Recv
{
public:
  // = Initialization methods.
  /// Default constructor.
  ACE_FIFO_Recv_Msg (void);

  /// Open up a record-oriented named pipe for reading.
  ACE_FIFO_Recv_Msg (const ACE_TCHAR *rendezvous,
                     int flags = O_CREAT | O_RDONLY,
                     mode_t perms = ACE_DEFAULT_FILE_PERMS,
                     int persistent = 1,
                     LPSECURITY_ATTRIBUTES sa = 0);

  /// Open up a record-oriented named pipe for reading.
  int open (const ACE_TCHAR *rendezvous,
            int flags = O_CREAT | O_RDONLY,
            mode_t perms = ACE_DEFAULT_FILE_PERMS,
            int persistent = 1,
            LPSECURITY_ATTRIBUTES sa = 0);

  /// Receive a message based on attributes in an ACE_Str_Buf.
  /**
   * @param msg  Reference to an ACE_Str_Buf whose @c buf member points
   *             to the memory to receive the data and @c maxlen member
   *             contains the maximum number of bytes to receive.
   *             On return after successfully reading data, the
   *             @c len member contains the number of bytes received and
   *             placed in the buffer pointed to by @c msg.buf.
   *
   * @retval -1  Error; consult @c errno for specific error number.
   * @return     If the @c ACE_HAS_STREAM_PIPES configuration setting is
   *             defined, the return value is the number of bytes received
   *             in the message and will be the same as @c buf.len.
   *             The return value from the @c getmsg() system function
   *             is discarded.
   *             If @c ACE_HAS_STREAM_PIPES is not defined, the number
   *             of bytes in the message read from the FIFO is returned.
   *             If the message is larger than the maximum length
   *             requested in @c msg.maxlen, the return value reflects
   *             the entire message length, and the @c msg.len member
   *             reflects how many bytes were actually placed in the
   *             caller's buffer. Any part of the message longer than
   *             @c msg.maxlen is discarded.
   */
  ssize_t recv (ACE_Str_Buf &msg);

  /// Receive a message based on buffer pointer and maximum size.
  /**
   * @param buf  Pointer to the memory to receive the data.
   * @param len  The maximum number of bytes to receive.
   *
   * @retval -1  Error; consult @c errno for specific error number.
   * @return     The number of bytes received in the message. For messages
   *             that are larger than the requested maximum size, the
   *             behavior is different depending on the @c ACE_HAS_STREAM_PIPES
   *             configuration setting. With @c ACE_HAS_STREAM_PIPES,
   *             the return value will be the same as @arg len (this is
   *             also possible if the message is exactly the same length
   *             as @arg len, and the two cases are indistinguishable).
   *             Without @c ACE_HAS_STREAM_PIPES, the return value is
   *             the total length of the message, including bytes in
   *             excess of @arg len. The excess bytes are discarded.
   */
  ssize_t recv (void *buf, size_t len);

#if defined (ACE_HAS_STREAM_PIPES)
  /// Recv <data> and <cntl> message via Stream pipes.
  ssize_t recv (ACE_Str_Buf *data,
                ACE_Str_Buf *cntl,
                int *flags);

  /// Recv <data> and <cntl> message via Stream pipes in "band" mode.
  ssize_t recv (int *band,
                ACE_Str_Buf *data,
                ACE_Str_Buf *cntl,
                int *flags);
#endif /* ACE_HAS_STREAM_PIPES */

  /// Dump the state of an object.
  void dump (void) const;

  /// Declare the dynamic allocation hooks.
  ACE_ALLOC_HOOK_DECLARE;
};

ACE_END_VERSIONED_NAMESPACE_DECL

#if defined (__ACE_INLINE__)
#include "ace/FIFO_Recv_Msg.inl"
#endif /* __ACE_INLINE__ */

#include /**/ "ace/post.h"
#endif /* ACE_FIFO_RECV_MSG_H */