kextsock.h

来自「konqueror3 embedded版本, KDE环境下的当家浏览器的嵌入式版」· C头文件 代码 · 共 1,111 行 · 第 1/3 页

  /**
   * Unsets the bind address for the socket. That means that we won't
   * attempt to bind to an address before connecting.
   * @return true if successful, false on error (e.g. connection already established)
   */
  bool unsetBindAddress();

  /**
   * Sets the timeout value for the connection (if this is not passiveSocket) or
   * acception (if it is). In the event the given function
   * (connect or accept) returns due to time out, it's possible to call it again.
   *
   * Setting the timeout to 0 disables the timeout feature.
   *
   * @param secs	the timeout length, in seconds
   * @param usecs	the timeout complement, in microseconds
   * @return false if setting timeout makes no sense in the context.
   */
  bool setTimeout(int secs, int usecs = 0);

  /**
   * Returns the timeout value for the connection.
   * @return the timeout value. 0 if there is no timeout.
   */
  timeval timeout() const;

  /**
   * Sets/unsets blocking mode for the socket. When non-blocking mode is enabled,
   * I/O operations might return error and set errno to EWOULDBLOCK. Also,
   * it's not recommended to use this when using the class signals.
   *
   * @param enable	if true, set blocking mode. False, non-blocking mode.
   * @return false on error.
   */
  bool setBlockingMode(bool enable);

  /**
   * Returns the current blocking mode for this socket.
   * @return true if in blocking mode
   */
  bool blockingMode();

  /**
   * Sets/unsets address reusing flag for this socket.
   *
   * This function returns true if the value was set correctly. That is NOT
   * the result of the set.
   * @param enable	if true, set address reusable
   * @return true on success, false on failure. If the socket was not yet created,
   * the value is only remembered. In this case the return value is always true.
   */
  bool setAddressReusable(bool enable);

  /**
   * Returns whether this socket's address can be reused
   * @return true if the address can be reused
   */
  bool addressReusable();

  /**
   * Sets/unsets the v6-only flag for IPv6 sockets.
   *
   * When an IPv6 socket is in use, communication with IPv4 sockets is
   * guaranteed by translating those IPv4 addresses into IPv6 ones
   * (specifically, the v4-mapped addresses). This flag allows that
   * behavior to be turned on and off.
   *
   * Note that this does not have any effect on sockets that are not
   * IPv6 and the function will always return false in those cases.
   * Also note that this flag defaults to off in order to accommodate
   * existing applications.
   *
   * @param enable	if true, no IPv4 translation will be performed;
   *			this socket will be restricted to IPv6 communication
   * @returns true on success, false on failure.
   * @see localAddress to find out if this is an IPv6 socket
   */
  bool setIPv6Only(bool enable);

  /**
   * Returns the status of the v6-only flag for IPv6 sockets.
   * @returns true if the flag is set to on; false if it is not. If this
   * socket is not an IPv6 one, the return value is false.
   * @see setIPv6Only
   */
  bool isIPv6Only();

  /**
   * Sets the buffer sizes for this socket.
   *
   * This implementation allows any size for both parameters. The value given
   * will be interpreted as the maximum size allowed for the buffers, after
   * which the I/O functions will stop buffering. The value of -1 will be
   * interpreted as "unlimited" size. The value of -2 means "no change".
   *
   * Note: changing the buffer size to 0 for any buffer will cause the given
   * buffer's to be discarded. Likewise, setting the size to a value less than
   * the current size will cause the buffer to be shrunk to the wanted value,
   * as if the data had been read.
   * @param rsize	read buffer size
   * @param wsize	write buffer size
   * @return true on success, false if this is not possible in this state (e.g. connection
   *         not established yet)
   */
  virtual bool setBufferSize(int rsize, int wsize = -2);

  /**
   * Returns the local socket address
   * @return the local socket address, can be 0 if the connection has not been established
   *         yet
   */
  const ::KSocketAddress *localAddress();

  /**
   * Returns the peer socket address. Use KExtendedSocket::resolve() to
   * resolve this to a human-readable hostname/service or port.
   * @return the peer address, can be 0 if the connection has not been established yet
   *         or the socket is passive
   */
  const ::KSocketAddress *peerAddress();

  /**
   * Returns the file descriptor
   * @return the file descriptor. -1 if there is no fd yet.
   */
  inline int fd() const
  { return sockfd; }

  /*
   * -- socket creation -- *
   */

  /**
   * Performs lookup on the addresses we were given before.
   *
   * This will perform lookups on the bind addresses if they were given.
   * @return 0 or an error. Do not rely on the values returned by lookup
   * as of now. They are not specified.
   */
  virtual int lookup();

  /**
   * Starts an asynchronous lookup for the addresses given.
   *
   * When the lookup is done, the lookupReady signal will be emitted.
   *
   * Note that, depending on the parameters for the lookup, this function might
   * know the results without the need for blocking or queuing an
   * asynchronous lookup. That means that the lookupReady signal might be
   * emitted by this function, so your code should be prepared for that.
   *
   * One such case is when noResolve flag is set.
   * If this function is able to determine the results without queuing
   * and the lookup failed, this function will return -1.
   *
   * @return 0 on success or -1 on error. Note that
   * returning 0 means that either we are in the process of doing
   * lookup or that it has finished already.
   */
  virtual int startAsyncLookup();

  /**
   * Cancels any on-going asynchronous lookups
   */
  virtual void cancelAsyncLookup();

  /**
   * Place the socket in listen mode. The parameters are the same as for
   * the system listen() call.
   * @param N		the queue length for pending connections
   * @return 0 on success, -1 on system error (errno
   *         available) and -2 if this is not a passiveSocket.
   */
  virtual int listen(int N = 5); // 5 is arbitrary

  /**
   * Accepts an incoming connection from the socket. If this socket is in
   * blocking mode, this function will block until a connection is received.
   * Otherwise, it might return with error. The sock parameter will be
   * initialised with the newly created socket.
   *
   * Upon successful acception (i.e., this function returns 0), the newly
   * created socket will be already connected. The socket will be unbuffered
   * and readyRead() and readyWrite() signals will be disabled.
   *
   * @param sock	a pointer to an KExtendedSocket variable
   * @return 0 on success, -1 on system error (errno set) and -2 if this is
   * not a passiveSocket and -3 if this took too long (time out)
   */
  virtual int accept(KExtendedSocket *&sock);

  /**
   * Attempts to connect to the remote host.
   * After successful connection (return value 0), the socket will be ready
   * for I/O operations. Note, however, that not all signals may be enabled
   * for emission by this socket:
   * @li readyRead and readyWrite signals will be enabled only if
   * enableRead or enableWrite were called. You can still enable
   *    them by calling those functions, of course.
   * @li #closed() will only be sent if we are indeed reading from the input
   *    stream. That is, if this socket is buffering the input. See setBufferSize
   *
   * Note that, in general, functions inherited/overridden from KBufferedIO will only
   * work on buffered sockets, like bytesAvailable and bytesToWrite.
   * @return    The return values are:
   * @li 0: success
   * @li -1: system error, errno was set accordingly
   * @li -2: this socket cannot connect(); this is a passiveSocket. It can also
   *   mean that the function was unable to make a connection with the given
   *   bind address or that an asynchronous connection attempt is already
   *   in progress.
   * @li -3: connection timed out
   *
   */
  virtual int connect();

  /**
   * Starts an asynchronous connect. This works exactly the same as #connect,
   * except that the connection result won't be returned.
   *
   * Note that those signals might be emitted before this function returns, so your
   * code should be prepared for that condition.
   *
   * You must call cancelAsyncConnect() before you delete the socket if you
   * call this.  Otherwise you will have crashes.
   *
   * @return 0 on successful queuing of the connect or -1 on error.
   *         If this function returns 0, then the connectionSuccess() or the
   * connectionFailed() signals will be emitted.
   */
  virtual int startAsyncConnect();

  /**
   * Cancels any on-going asynchronous connection attempt.
   */
  virtual void cancelAsyncConnect();

  /**
   * Implementation of QIODevice::open() pure virtual function.
   * This depends on the target host address already being there.
   * If this is a passiveSocket, this is identical to call listen(); else, if
   * this is not a passiveSocket and no connection attempt is in progress, this
   * is like connect(). If one is in progress, this function will fail.
   * @param mode the open mode. Must be IO_Raw | IO_ReadWrite
   * @return true if successful, false when an error occurred or the most was
   *         not correct
   */
  virtual bool open(int mode = IO_Raw | IO_ReadWrite);

  /**
   * Closes the socket. If we have data still in the write buffer yet to be
   * sent, the socket won't be closed right now. It'll be closed after we managed
   * to send everything out.
   * If you want to close the socket now, you may want to call flush() first,
   * and then closeNow().
   */
  virtual void close();

  /**
   * Closes the socket now, discarding the contents of the write buffer, if any.
   * The read buffer's contents are kept until they are emptied by read operations
   * or the class is destroyed.
   */
  virtual void closeNow();

  /**
   * Releases the socket and anything we have holding on it. The class cannot
   * be used anymore. In other words, this is just like closeNow(), but it does
   * not actually close the socket.
   *
   * This is useful if you just want to connect and don't need the rest of the
   * class.
   *
   * Note that the buffers' contents will be discarded.
   *
   * Use of this method is discouraged, because the socket created might be such that
   * normal library routines can't handle (read, write, close, etc.)
   */
  virtual void release();

  /*
   * -- I/O --
   */

  /**
   * Flushes the socket buffer. You need not call this method during normal
   * operation as we will try and send everything as soon as possible.
   * However, if you want to make sure that data in the buffer is being sent
   * at this moment, you can call this function. It will try to send as much
   * data as possible, but it will stop as soon as the kernel cannot receive
   * any more data, and would possibly block.
   *
   * By repeatedly calling this function, the behavior will be like that of
   * a blocking socket. Indeed, if this function is called with the kernel not
   * ready to receive data, it will block, unless this is a non-blocking socket.
   *
   * This function does not touch the read buffer. You can empty it by calling
   * readBlock() with a null destination buffer.
   */
  virtual void flush();

  /**
   * Returns length of this socket. This call is not supported on sockets.
   * @return the length of this socket, or 0 if unsupported
   */
  virtual inline Q_ULONG size() const
  { return 0; }

  /**
   * Returns relative position from start. This call is not supported on sockets.
   * @return the relative position from the start, or 0 if unsupported
   */
  virtual inline Q_ULONG at() const
  { return 0; }

  /**
   * Returns true if we are at position. This is not supported on sockets.
   * @param i the position to check
   * @return true if we art at the given position, or always true if unsupported.
   */
  virtual inline bool at(int i)
  { Q_UNUSED(i);return true; }

  /**
   * Returns true if we are at the end. This is not supported on sockets, but
   * we always are at the end in a socket...
   * @return true if we are at the end. Always false if unsupported.
   */
  virtual inline bool atEnd() const
  { return false; }

  /**
   * Reads a block of data from the socket.
   *
   * If the socket is not buffered, this function will simply call the underlying
   * read method. This function will block if the socket is not on non-blocking mode
   * (see setBlockingMode) and there is not enough data to be read in the
   * Operating System yet. If we are in non-blocking operation, the call will
   * fail in this case.
   *
   * However, if we are buffering, this function will instead read from the
   * buffer while there is available data. This function will never block
   * in buffering mode, which means that if you try to read while the buffers
   * are empty, this function will always return -1 and set the system error to
   * EWOULDBLOCK (aka EAGAIN), so as to mimic non-blocking operation.
   *
   * @param data	where we will write the read data to
   * @param maxlen	maximum length of data to be read
   * @return the number of bytes effectively read, or a negative number in case
   * or an error. If the @p data param is not null, then this is also the number
   * of bytes copied into that buffer. If the return value is different than
   * @p maxlen, then this function encountered a situation in which no more
   * bytes were available. Subsequent calls might cause this function to one
   * of these behaviours:
   * @li return an error, with EWOULDBLOCK system error, if we buffering
   *   or we are in non-blocking mode
   * @li otherwise, it'll block
   * This function returns 0, if the function detected end-of-file condition
   * (socket was closed)
   */
  virtual Q_LONG readBlock(char *data, Q_ULONG maxlen);

  /**
   * Writes a block of data to the socket.
   *
   * If the socket is not buffered, this function will simply call the underlying
   * write method. This means that the function might block if that method blocks
   * as well. That situation is possible if we are not in non-blocking mode and
   * the operating system buffers are full for this socket. If we are in
   * non-blocking mode and the operating system buffers are full, this function