kextsock.h

来自「将konqueror浏览器移植到ARM9 2410中」· C头文件 代码 · 共 820 行 · 第 1/2 页

   */
  virtual void cancelAsyncLookup();

  /**
   * Place the socket in listen mode. The parameters are the same as for
   * the system listen() call. Returns 0 on success, -1 on system error (errno
   * available) and -2 if this is not a passiveSocket.
   * @param N		the queue length for pending connections
   */
  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.
   * Returns 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)
   * @param sock	a pointer to an KExtendedSocket variable
   */
  virtual int accept(KExtendedSocket *&sock);

  /**
   * Attempts to connect to the remote host. The return values are:
   * 0: success
   * -1: system error, errno was set accordingly
   * -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.
   * -3: connection timed out
   */
  virtual int connect();

  /**
   * Starts an asynchronous connect. This works exactly the same as @ref connect,
   * except that the connection result won't be returned. This function will 
   * return either 0 on successful queueing of the connect or -1 on error. If 
   * this function returns 0, then the connectionSuccess or the connectionFailed
   * signals will be emitted.
   * Note that those signals might be emitted before this function returns, so your
   * code should be prepared for that condition.
   */
  virtual int startAsyncConnect();

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

  /**
   * Implementation of QIODevice's 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
   */
  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 @ref flush first,
   * and then @ref 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. And usage 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 behaviour 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
   * @ref readBlock with a null destination buffer.
   */
  virtual void flush();

  /**
   * Returns length of this socket. This call is not supported on sockets
   */
  virtual inline uint size() const
  { return 0; }

  /**
   * Returns relative position from start. This call is not supported on sockets
   */
  virtual inline int at() const
  { return 0; }

  /**
   * Returns true if we are at position. This is not supported on sockets
   */
  virtual inline bool at(int)
  { 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...
   */
  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 @ref 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.
   *
   * The return value for this function is the number of bytes effectively
   * read. 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:
   * - block, if we are not buffering and we are not in non-blocking mode
   * - return an error, with EWOULDBLOCK system error, if we buffering
   *   or we are in non-blocking mode
   * This function returns 0, if the function detected end-of-file condition
   * (socket was closed)
   *
   * @param data	where we will write the read data to
   * @param maxlen	maximum length of data to be read
   */
  virtual int readBlock(char *data, uint 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
   * will return -1 and the system error will be set to EWOULDBLOCK.
   * If we are buffering, this function will simply transfer the data into the
   * write buffer. This function will always succeed, as long as there is
   * enough room in the buffer. If the buffer size was limited and that limit
   * is reached, this function will copy no more bytes than that limit. Trying
   * to write with a full buffer will return -1 and set system error to
   * EWOULDBLOCK.
   *
   * The function returns the number of bytes written from @p data buffer.
   * The return value might be less than @p len if the output buffers cannot
   * accomodate that many bytes.
   *
   * @param data	the data to write
   * @param len		the length of data to write
   */
  virtual int writeBlock(const char *data, uint len);

  /**
   * peeks at a block of data from the socket
   * This is exactly like read, except that the data won't be flushed from the
   * read buffer.
   * If this socket is not buffered, this function will always return with
   * 0 bytes copied.
   * The return value of 0 does not mean end-of-file condition.
   * @param data	where to store the data
   * @param maxlen	how many bytes to copy, at most
   */
  virtual int peekBlock(char *data, uint maxlen);

  /**
   * reimplementation of unreadBlock method. This is so because unreading in 
   * sockets doesn't make sense, so this function will always return -1 (error)
   * and set the system error to ENOSYS.
   */
  virtual int unreadBlock(const char *data, uint len);

  /**
   * Waits @p msec milliseconds for more data to be available, or 0 to
   * wait forever. The return value is the amount of data available for
   * read in the read buffer.
   * This function returns -1 in case of system error and -2 in case of
   * invalid socket state
   * @param msec	milliseconds to wait
   */
  virtual int waitForMore(int msec);

  /**
   * gets a single character from the stream
   */
  virtual int getch();

  /**
   * writes a single character to the stream
   * @param ch		character to write, converted to char
   */
  virtual int putch(int ch);

  /**
   * unreads one character from the stream. This is not possible on sockets
   */
  virtual int ungetch(int)
  { return -1; }

  /**
   * Toggles the emission of the readyRead signal
   * Note that this signal is emitted every time more data is available to be
   * read, so you might get flooded with it being emitted every time, when in
   * non-buffered mode. However, in buffered mode, this signal will be
   * emitted only when there is data coming in from the wire.
   * By default, this flag is set to false, i.e., signal not being emitted.
   * @param enable	if true, the signal will be emitted
   */
  virtual void enableRead(bool enable);

  /**
   * Toggles the emission of the readyWrite signal
   * Note that this signal is emitted only when the OS is ready to receive more
   * data, which means that the write buffer is empty. And when that is reached,
   * this signal will possibly be emitted on every loop, so you might
   * want to disable it. By default, this flag is set to false.
   * @param enable	if true, the signal will be emitted
   */
  virtual void enableWrite(bool enable);

signals:
  /**
   * This signal is emitted whenever an asynchronous lookup process is done.
   * The parameter @p count tells how many results were found.
   */
  void lookupFinished(int count);

  /**
   * This signal is emitted whenever we connected asynchronously to a host.
   */
  void connectionSuccess();

  /**
   * This signal is emitted whenever our asynchronous connection attempt
   * failed to all hosts listed.
   * @param error	the errno code of the last connection attempt
   */
  void connectionFailed(int error);

protected:
  int m_flags;			// current flags
  int m_status;			// status
  int m_syserror;		// the system error code

  int sockfd;			// file descriptor of the socket

protected slots:

  void socketActivityRead();
  void socketActivityWrite();
  void dnsResultsReady();
  void startAsyncConnectSlot();
  void connectionEvent();

private:
  class KExtendedSocketPrivate;
  KExtendedSocketPrivate *d;

  // protection against accidental use
  KExtendedSocket(KExtendedSocket&);
  KExtendedSocket& operator=(KExtendedSocket&);

protected:
  /**
   * Sets the error code
   */
  void setError(int errorkind, int error);

  inline void cleanError()
  { setError(IO_Ok, 0); }

  /**
   * This is actually a wrapper around getaddrinfo()
   * @internal
   */
  static int doLookup(const QString& host, const QString& serv, addrinfo& hint,
		      kde_addrinfo** result);

public:
  /**
   * Performs resolution on the given socket address
   * That is, tries to resolve the raw form of the socket address into a textual
   * representation.
   * @param sockaddr	the socket address
   * @param host	where the hostname will be written
   * @param port	where the service-port will be written
   * @param flags	the same flags as getnameinfo()
   */
  static int resolve(sockaddr* sock, ksocklen_t len, QString& host, QString& port, int flags = 0);
  static int resolve(KSocketAddress* sock, QString& host, QString& port, int flags = 0);

  /**
   * Performs lookup on the given hostname/port combination and returns a list
   * of matching addresses.
   * The error code can be transformed into string by @ref KExtendedSocket::strError
   * with code of IO_LookupError.
   *
   * IMPORTANT: the result values of the QList must be deleted after use. So,
   * if you don't copy the KAddressInfo objects, the best way to assure that
   * is to call setAutoDelete(true) on the list right after this function 
   * returns. If you do copy the results out, you must assure that the objects
   * get deleted when they are not needed any more.
   *
   * @param host	the hostname to look up
   * @param port	the port/service to look up
   * @param flags	flags to be used when looking up, @see Flags
   * @param error	pointer to a variable holding the error code
   */
  static QList<KAddressInfo> lookup(const QString& host, const QString& port, int flags = 0, int *error = 0);

  /**
   * Returns the local socket address
   * Remember to delete the returned object when it is no longer needed.
   * @param fd		the file descriptor
   */
  static KSocketAddress *localAddress(int fd);

  /**
   * Returns the peer socket address. Use KExtendedSocket::resolve() to
   * resolve this to a human-readable hostname/service or port.
   * Remember to delete the returned object when it is no longer needed.
   * @param fd		the file descriptor
   */
  static KSocketAddress *peerAddress(int fd);

  /**
   * Returns the representing text of this error code
   * @param code	the error code, as seen in status()
   * @param syserr	the system error, as from systemError()
   */
  static QString strError(int code, int syserr);
};

class KAddressInfo
{
private:
  addrinfo *ai;
  KSocketAddress *addr;

  inline KAddressInfo() : ai(0), addr(0)
  { }

  KAddressInfo(addrinfo *ai);
  KAddressInfo(KAddressInfo&) { }
  KAddressInfo& operator=(KAddressInfo&) { return *this; }

public:
  ~KAddressInfo();

  inline operator const KSocketAddress*() const
  { return addr; }

  inline operator const addrinfo&() const
  { return *ai; }

  inline operator const addrinfo*() const
  { return ai; }

  inline const KSocketAddress* address() const
  { return addr; }

  int flags() const;
  int family() const;
  int socktype() const;
  int protocol() const;
  const char* canonname() const;

  inline int length() const
  { if (addr) return addr->size(); return 0; }

  friend class KExtendedSocket;
};

#endif // KEXTSOCK_H