Qt之QLocalServer

简述

QLocalServer提供了一个基于本地socket的server。

QLocalServer可以接受来自本地socket的连接。通过调用listen()，让server监听来自特定key的连接。

调用nextPendingConnection()来接受一个挂起（等待）的连接作为一个已连接的QLocalSocket。函数返一个QLocalSocket指针，可以被用于和client通信。

如果发生错误，serverError()会返回错误的类型，errorString()则返回人类可读的错误描述。

当监听连接时，通过serverName()可以获取当前server监听的名称。

调用close()使QLocalServer停止对连接请求的监听。

虽然QLocalServer被设计用于事件循环，但在没有事件循环时也是可以使用的。这时必须使用waitForNewConnection()来进行阻塞，直到有可用的连接或超时。

成员类型

枚举 QLocalServer::SocketOption
标识 QLocalServer::SocketOptions

常量	值	描述
QLocalServer::NoOptions	0x0	没有设置访问限制
QLocalServer::UserAccessOption	0x01	访问仅限于相同的用户进程创建的套接字。
QLocalServer::GroupAccessOption	0x2	在Linux中，访问仅限于同一组，但不是创建socket的用户；在Windows中，访问仅限于进程的主要组
QLocalServer::OtherAccessOption	0x4	在Linux中，访问对每个人来说都可用，除了创建socket的用户和组；在Windows中，访问对每个人来说都可用。
QLocalServer::WorldAccessOption	0x7	没有访问限制

socketOptions : SocketOptions

setSocketOptions()函数控制socket操作。例如：socket可能限制可以连接到socket的user ids。

在listen()调用之前，这些选项必须被设置。

在某些情况下，例如：在Linux上的Unix domain sockets，socket的访问将由文件系统权限决定，并基于umask创建。设置访问标识，将覆盖这，并且限制或允许访问指定。

其它基于Unix的操作系统，例如：OS X，不在意Unix domain sockets的文件权限，并且默认情况下WorldAccess和这些许可标志将没有影响。

在Windows中，UserAccessOption足以让一个非提升进程连接到由一个提升的进程创建的本地server，由相同的用户。 GroupAccessOption指的是进程（见Windows文档中的TokenPrimaryGroup）的主组。 OtherAccessOption指的是著名的“Everyone”组。

默认情况下，没有设置任何标识，访问权限是平台默认的。

Public函数

void close()

停止监听传入的连接。现有连接将不受影响，但任何新的连接将被拒绝。

QString errorString() const

返回人类可读的消息，适合serverError()报告的当前错误。如果没有合适的字符串，则返回一个空字符串。

QString fullServerName() const

返回server监听的完整路径。

注意：这取决于平台

virtual bool hasPendingConnections() const

如果server有一个等待中的连接，返回true；否则返回false。

bool isListening() const

如果server正在监听传入的连接，返回true；否则返回false。

bool listen(const QString &name)

告诉server监听名为name的传入连接。如果server当前正在侦听，返回false；成功返回true，否则返回false。

名称可以是单个名称，QLocalServer将决定正确的特定于平台的路径。serverName()返回传递给listen()的name。

通常，只需要传入类似“foo”的name即可。但在Unix中，这个name也可以是一个路径，例如：“/tmp/foo”；在windows中，name也可以指定为一个管道路径，例如：“\.\pipe\foo”。

注意：在Unix中，如果server没有关闭listen就crash了，会产生一个AddressInUseError的错误。要想创建一个新的server，需要移除这个file。在windows中，两个本地server可以同时监听同一个管道，但任何连接将会选择其中的一个server。

bool listen(qintptr socketDescriptor)

指示server监听传入的socketDescriptor连接。如果server目前正在倾听，返回false，成功返回true；否则返回false。socket 必须准备接受新连接，没有额外的特定于平台的功能。socket被设置为非阻塞模式。

如果平台支持该选项，serverName()、fullServerName()返回一个name字符串；否则，返回一个空字符串。

int maxPendingConnections() const

返回可接受的最大的等待连接数，默认为30。

virtual QLocalSocket *nextPendingConnection()

返回下一个等待中的连接作为已连接上的QLocalSocket对象。

创建的socket被当作是server的孩子，这意味着当QLocalServer对象被销毁时，socket会被自动删除。
为避免内存浪费，仍然可以在使用完socket之后，显式地删除它。

当没有等待的连接时，调用该函数返回值0。

QAbstractSocket::SocketError serverError() const

返回最后发生的错误类型或NoError。

QString serverName() const

如果server正在监听连接，返回server名称；否则返回QString()。

void setMaxPendingConnections(int numConnections)

设置可接收的最大等待连接数为numConnections。QLocalServer在调用nextPendingConnection()之前，最多只能接受numConnections个连接请求。

注意：尽管QLocalServer在等待的连接数目达到设置的最大值之后，将不再接受新的连接请求，但是操作系统仍然会将这些新的连接请求保持在等待队列中，因为这些请求在连接上之后会给客户端发送信号。

void setSocketOptions(SocketOptions options)

设置socket的socket选项。

SocketOptions socketOptions() const

返回设置在socket上的socket选项。

bool waitForNewConnection(int msec = 0, bool *timedOut = Q_NULLPTR)

最多等待msec毫秒，直到一个传入的连接可用。如果一个连接可用，返回ture，否则返回false。如果操作超时并且timedOut不为0，则将*timedOut设置为ture。

这是一个阻塞函数调用，在单线程GUI应用程序中使用不太明智，因为在该函数返回之前，整个应用程序将停止对其他事件的响应。当没有事件循环时，waitForNewConnection()很有用。

非阻塞的替代方案是连接到newConnection()信号。

如果msec为-1，该函数不会超时。

信号

void newConnection()

每次一个新连接可用时，发射此信号。

Static Public函数

bool removeServer(const QString &name)

移除可能导致调用listen()失败的任何server实例，如果成功，返回true；否则返回false。这个函数是为了从crash中恢复，当以前的server实例没有被清理干净。

在Windows中，此函数不进行任何操作；在Unix中，它移除由name指定的socket文件。

警告：应该注意避免移除正处于运行状态的socke实例。

Protected函数

virtual void incomingConnection(quintptr socketDescriptor)

当一个新连接可用时，这个虚函数就会被QLocalServer调用， socketDescriptor是接受的连接的本地socket描述符。

基本实现创建一个QLocalSocket，设置socket描述符，然后将这个QLocalSocket存入到待连接的一张内部列表中。最后发射newConnection()信号。

重写这个函数，当有可用连接时，可以改变server的行为。