Class SocketDMChannel

Namespace

Kook.WebSocket

Assembly

Kook.Net.WebSocket.dll

表示一个基于网关的私聊频道。

public class SocketDMChannel : SocketChannel, IUpdateable, IDMChannel, IEntity<Guid>, ISocketPrivateChannel, IPrivateChannel, ISocketMessageChannel, IMessageChannel, IChannel, IEntity<ulong>

Inheritance

object

SocketEntity<ulong>

SocketChannel

SocketDMChannel

Implements

IUpdateable

IDMChannel

IEntity<Guid>

ISocketPrivateChannel

IPrivateChannel

ISocketMessageChannel

IMessageChannel

IChannel

IEntity<ulong>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

Extension Methods

ChannelExtensions.GetChannelType(IChannel)

ChannelExtensions.GetJumpUrl(IChannel)

Properties

CachedMessages

获取此频道缓存的所有消息。

public IReadOnlyCollection<SocketMessage> CachedMessages { get; }

Property Value

IReadOnlyCollection<SocketMessage>

Remarks

warning

要想通过此属性获取缓存的消息，需要启用缓存功能，否则此属性将始终返回空集合。缓存功能是默认禁用的，要想启用缓存，请参考 MessageCacheSize。

此属性从本地的内存缓存中获取消息实体，不会向 KOOK 发送额外的 API 请求。所获取的消息也可能是已经被删除的消息。

ChatCode

获取此私聊频道的聊天代码。

public Guid ChatCode { get; }

Property Value

Guid

Remarks

此属性的值与 Id 相同。

Id

获取此私聊频道的唯一标识符。

public Guid Id { get; }

Property Value

Guid

Remarks

此属性的值与 ChatCode 相同。

Recipient

获取参与到此私聊频道的另外一位用户。

public SocketUser Recipient { get; }

Property Value

SocketUser

Users

获取用户缓存列表中的可以访问此频道的所有用户。

public IReadOnlyCollection<SocketUser> Users { get; }

Property Value

IReadOnlyCollection<SocketUser>

Remarks

此属性仅会返回缓存中可以访问此频道的所有用户，如果未启用用户列表缓存，或者由于网关事件确实导致本地缓存不同步，此属性所返回的用户列表可能不准确。

Methods

CloseAsync(RequestOptions?)

关闭此私聊频道，将其从您的频道列表中移除。

public Task CloseAsync(RequestOptions? options = null)

Parameters

options RequestOptions

发送请求时要使用的选项。

Returns

Task

一个表示异步关闭操作的任务。

DeleteMessageAsync(IMessage, RequestOptions?)

删除一条消息.

public Task DeleteMessageAsync(IMessage message, RequestOptions? options = null)

Parameters

message IMessage

要删除的消息。

options RequestOptions

发送请求时要使用的选项。

Returns

Task

一个表示异步删除操作的任务。

DeleteMessageAsync(Guid, RequestOptions?)

删除一条消息。

public Task DeleteMessageAsync(Guid messageId, RequestOptions? options = null)

Parameters

messageId Guid

要删除的消息的 ID。

options RequestOptions

发送请求时要使用的选项。

Returns

Task

一个表示异步删除操作的任务。

GetCachedMessage(Guid)

获取此频道缓存的消息。

public SocketMessage? GetCachedMessage(Guid id)

Parameters

id Guid

消息的 ID。

Returns

SocketMessage

如果获取到了缓存的消息，则返回该消息实体；否则返回 null。

Remarks

warning

要想通过此方法获取缓存的消息，需要启用缓存功能，否则此方法将始终返回 null。缓存功能是默认禁用的，要想启用缓存，请参考 MessageCacheSize。

此方法从本地的内存缓存中获取消息实体，不会向 KOOK 发送额外的 API 请求。所获取的消息也可能是已经被删除的消息。

GetCachedMessages(IMessage, Direction, int)

获取此频道缓存的多条消息。

public IReadOnlyCollection<SocketMessage> GetCachedMessages(IMessage referenceMessage, Direction dir, int limit = 50)

Parameters

referenceMessage IMessage

要开始获取消息的参考位置的消息。

dir Direction

要以参考位置为基准，获取消息的方向。

limit int

要获取的消息数量。

Returns

IReadOnlyCollection<SocketMessage>

获取到的多条缓存消息。

Remarks

warning

要想通过此方法获取缓存的消息，需要启用缓存功能，否则此方法将始终返回空集合。缓存功能是默认禁用的，要想启用缓存，请参考 MessageCacheSize。

此方法从本地的内存缓存中获取消息实体，不会向 KOOK 发送额外的 API 请求。所获取的消息也可能是已经被删除的消息。

GetCachedMessages(Guid, Direction, int)

获取此频道缓存的多条消息。

public IReadOnlyCollection<SocketMessage> GetCachedMessages(Guid referenceMessageId, Direction dir, int limit = 50)

Parameters

referenceMessageId Guid

要开始获取消息的参考位置的消息的 ID。

dir Direction

要以参考位置为基准，获取消息的方向。

limit int

要获取的消息数量。

Returns

IReadOnlyCollection<SocketMessage>

获取到的多条缓存消息。

Remarks

warning

要想通过此方法获取缓存的消息，需要启用缓存功能，否则此方法将始终返回空集合。缓存功能是默认禁用的，要想启用缓存，请参考 MessageCacheSize。

此方法从本地的内存缓存中获取消息实体，不会向 KOOK 发送额外的 API 请求。所获取的消息也可能是已经被删除的消息。

GetCachedMessages(int)

获取此频道缓存的多条消息。

public IReadOnlyCollection<SocketMessage> GetCachedMessages(int limit = 50)

Parameters

limit int

要获取的缓存消息的数量。

Returns

IReadOnlyCollection<SocketMessage>

此频道缓存的所有消息。

Remarks

此重载将会从缓存中获取最新的指定数量的缓存消息实体。

warning

要想通过此方法获取缓存的消息，需要启用缓存功能，否则此方法将始终返回空集合。缓存功能是默认禁用的，要想启用缓存，请参考 MessageCacheSize。

此方法从本地的内存缓存中获取消息实体，不会向 KOOK 发送额外的 API 请求。所获取的消息也可能是已经被删除的消息。

GetMessageAsync(Guid, RequestOptions?)

从此消息频道获取一条消息。

public Task<IMessage> GetMessageAsync(Guid id, RequestOptions? options = null)

Parameters

id Guid

消息的 ID。

options RequestOptions

发送请求时要使用的选项。

Returns

Task<IMessage>

一个表示异步获取操作的任务。任务结果包含检索到的消息；如果未找到具有指定 ID 的消息，则返回 null。

GetMessagesAsync(IMessage, Direction, int, RequestOptions?)

获取此消息频道中的一些消息。

public IAsyncEnumerable<IReadOnlyCollection<IMessage>> GetMessagesAsync(IMessage referenceMessage, Direction dir, int limit = 50, RequestOptions? options = null)

Parameters

referenceMessage IMessage

要开始获取消息的参考位置的消息。

dir Direction

要以参考位置为基准，获取消息的方向。

limit int

要获取的消息数量。

options RequestOptions

发送请求时要使用的选项。

Returns

IAsyncEnumerable<IReadOnlyCollection<IMessage>>

分页的消息集合的异步可枚举对象。

Remarks

important

返回的集合是一个异步可枚举对象；调用 FlattenAsync<T>(IAsyncEnumerable<IEnumerable<T>>) 可以异步枚举所有分页，并将其合并为一个集合。

warning

请勿一次性获取过多消息，这可能会导致抢占式速率限制，甚至触发实际的速率限制，从而导致 Bot 服务暂停。

此方法将尝试获取此频道最新的 limit 条消息。此方法会根据 MaxMessagesPerBatch 将请求拆分。换句话说，如果要获取 500 条消息，而 MaxMessagesPerBatch 的常量为 50，则请求将被拆分为 10 个单独请求，因此异步枚举器会异步枚举返回 10 个响应。 FlattenAsync<T>(IAsyncEnumerable<IEnumerable<T>>) 方法可以展开这 10 个响应返回的集合，并将其合并为一个集合。

GetMessagesAsync(Guid, Direction, int, RequestOptions?)

获取此消息频道中的一些消息。

public IAsyncEnumerable<IReadOnlyCollection<IMessage>> GetMessagesAsync(Guid referenceMessageId, Direction dir, int limit = 50, RequestOptions? options = null)

Parameters

referenceMessageId Guid

要开始获取消息的参考位置的消息的 ID。

dir Direction

要以参考位置为基准，获取消息的方向。

limit int

要获取的消息数量。

options RequestOptions

发送请求时要使用的选项。

Returns

IAsyncEnumerable<IReadOnlyCollection<IMessage>>

分页的消息集合的异步可枚举对象。

Remarks

important

返回的集合是一个异步可枚举对象；调用 FlattenAsync<T>(IAsyncEnumerable<IEnumerable<T>>) 可以异步枚举所有分页，并将其合并为一个集合。

warning

请勿一次性获取过多消息，这可能会导致抢占式速率限制，甚至触发实际的速率限制，从而导致 Bot 服务暂停。

此方法将尝试获取此频道最新的 limit 条消息。此方法会根据 MaxMessagesPerBatch 将请求拆分。换句话说，如果要获取 500 条消息，而 MaxMessagesPerBatch 的常量为 50，则请求将被拆分为 10 个单独请求，因此异步枚举器会异步枚举返回 10 个响应。 FlattenAsync<T>(IAsyncEnumerable<IEnumerable<T>>) 方法可以展开这 10 个响应返回的集合，并将其合并为一个集合。

GetMessagesAsync(int, RequestOptions?)

获取此消息频道中的最新的一些消息。

public IAsyncEnumerable<IReadOnlyCollection<IMessage>> GetMessagesAsync(int limit = 50, RequestOptions? options = null)

Parameters

limit int

要获取的消息数量。

options RequestOptions

发送请求时要使用的选项。

Returns

IAsyncEnumerable<IReadOnlyCollection<IMessage>>

分页的消息集合的异步可枚举对象。

Remarks

important

返回的集合是一个异步可枚举对象；调用 FlattenAsync<T>(IAsyncEnumerable<IEnumerable<T>>) 可以异步枚举所有分页，并将其合并为一个集合。

warning

请勿一次性获取过多消息，这可能会导致抢占式速率限制，甚至触发实际的速率限制，从而导致 Bot 服务暂停。

此方法将尝试获取此频道最新的 limit 条消息。此方法会根据 MaxMessagesPerBatch 将请求拆分。换句话说，如果要获取 500 条消息，而 MaxMessagesPerBatch 的常量为 50，则请求将被拆分为 10 个单独请求，因此异步枚举器会异步枚举返回 10 个响应。 FlattenAsync<T>(IAsyncEnumerable<IEnumerable<T>>) 方法可以展开这 10 个响应返回的集合，并将其合并为一个集合。

GetUser(ulong)

获取此频道中的一个用户。

public SocketUser? GetUser(ulong id)

Parameters

id ulong

要获取的用户的 ID。

Returns

SocketUser

如果找到了具有指定 ID 的用户，则返回该用户；否则返回 null。

ModifyMessageAsync(Guid, Action<MessageProperties>, RequestOptions?)

修改一条消息。

public Task ModifyMessageAsync(Guid messageId, Action<MessageProperties> func, RequestOptions? options = null)

Parameters

messageId Guid

要修改的消息的 ID。

func Action<MessageProperties>

一个包含修改消息属性的委托。

options RequestOptions

发送请求时要使用的选项。

Returns

Task

一个表示异步修改操作的任务。

See Also

MessageProperties

ModifyMessageAsync<T>(Guid, Action<MessageProperties<T>>, RequestOptions?)

修改一条消息。

public Task ModifyMessageAsync<T>(Guid messageId, Action<MessageProperties<T>> func, RequestOptions? options = null)

Parameters

messageId Guid

要修改的消息的 ID。

func Action<MessageProperties<T>>

一个包含修改消息属性的委托。

options RequestOptions

发送请求时要使用的选项。

Returns

Task

一个表示异步修改操作的任务。

Type Parameters

T

模板参数的类型。

See Also

MessageProperties

SendCardAsync(ICard, IQuote?, RequestOptions?)

发送卡片消息到此消息频道。

public Task<Cacheable<IUserMessage, Guid>> SendCardAsync(ICard card, IQuote? quote = null, RequestOptions? options = null)

Parameters

card ICard

要发送的卡片。

quote IQuote

消息引用，用于回复消息。

options RequestOptions

发送请求时要使用的选项。

Returns

Task<Cacheable<IUserMessage, Guid>>

一个表示异步发送操作的任务。任务的结果包含所发送消息的可延迟加载的消息对象。

SendCardsAsync(IEnumerable<ICard>, IQuote?, RequestOptions?)

发送卡片消息到此消息频道。

public Task<Cacheable<IUserMessage, Guid>> SendCardsAsync(IEnumerable<ICard> cards, IQuote? quote = null, RequestOptions? options = null)

Parameters

cards IEnumerable<ICard>

要发送的卡片。

quote IQuote

消息引用，用于回复消息。

options RequestOptions

发送请求时要使用的选项。

Returns

Task<Cacheable<IUserMessage, Guid>>

一个表示异步发送操作的任务。任务的结果包含所发送消息的可延迟加载的消息对象。

SendCardsAsync<T>(int, T, IQuote?, JsonSerializerOptions?, RequestOptions?)

发送卡片消息到此消息频道。

public Task<Cacheable<IUserMessage, Guid>> SendCardsAsync<T>(int templateId, T parameters, IQuote? quote = null, JsonSerializerOptions? jsonSerializerOptions = null, RequestOptions? options = null)

Parameters

templateId int

消息模板的 ID。

parameters T

传入消息模板的参数。

quote IQuote

消息引用，用于回复消息。

jsonSerializerOptions JsonSerializerOptions

序列化模板参数时要使用的序列化选项。

options RequestOptions

发送请求时要使用的选项。

Returns

Task<Cacheable<IUserMessage, Guid>>

一个表示异步发送操作的任务。任务的结果包含所发送消息的可延迟加载的消息对象。

Type Parameters

T

参数的类型。

SendFileAsync(FileAttachment, IQuote?, RequestOptions?)

发送文件到此消息频道。

public Task<Cacheable<IUserMessage, Guid>> SendFileAsync(FileAttachment attachment, IQuote? quote = null, RequestOptions? options = null)

Parameters

attachment FileAttachment

文件的附件信息。

quote IQuote

消息引用，用于回复消息。

options RequestOptions

发送请求时要使用的选项。

Returns

Task<Cacheable<IUserMessage, Guid>>

一个表示异步发送操作的任务。任务的结果包含所发送消息的可延迟加载的消息对象。

SendFileAsync(Stream, string, AttachmentType, IQuote?, RequestOptions?)

发送文件到此消息频道。

public Task<Cacheable<IUserMessage, Guid>> SendFileAsync(Stream stream, string filename, AttachmentType type = AttachmentType.File, IQuote? quote = null, RequestOptions? options = null)

Parameters

stream Stream

文件的流。

filename string

文件名。

type AttachmentType

文件的媒体类型。

quote IQuote

消息引用，用于回复消息。

options RequestOptions

发送请求时要使用的选项。

Returns

Task<Cacheable<IUserMessage, Guid>>

一个表示异步发送操作的任务。任务的结果包含所发送消息的可延迟加载的消息对象。

SendFileAsync(string, string?, AttachmentType, IQuote?, RequestOptions?)

发送文件到此消息频道。

public Task<Cacheable<IUserMessage, Guid>> SendFileAsync(string path, string? filename = null, AttachmentType type = AttachmentType.File, IQuote? quote = null, RequestOptions? options = null)

Parameters

path string

文件的路径。

filename string

文件名。

type AttachmentType

文件的媒体类型。

quote IQuote

消息引用，用于回复消息。

options RequestOptions

发送请求时要使用的选项。

Returns

Task<Cacheable<IUserMessage, Guid>>

一个表示异步发送操作的任务。任务的结果包含所发送消息的可延迟加载的消息对象。

SendTextAsync(string, IQuote?, RequestOptions?)

发送文本消息到此消息频道。

public Task<Cacheable<IUserMessage, Guid>> SendTextAsync(string text, IQuote? quote = null, RequestOptions? options = null)

Parameters

text string

要发送的文本。

quote IQuote

消息引用，用于回复消息。

options RequestOptions

发送请求时要使用的选项。

Returns

Task<Cacheable<IUserMessage, Guid>>

一个表示异步发送操作的任务。任务的结果包含所发送消息的可延迟加载的消息对象。

SendTextAsync<T>(int, T, IQuote?, JsonSerializerOptions?, RequestOptions?)

发送文本消息到此消息频道。

public Task<Cacheable<IUserMessage, Guid>> SendTextAsync<T>(int templateId, T parameters, IQuote? quote = null, JsonSerializerOptions? jsonSerializerOptions = null, RequestOptions? options = null)

Parameters

templateId int

消息模板的 ID。

parameters T

传入消息模板的参数。

quote IQuote

消息引用，用于回复消息。

jsonSerializerOptions JsonSerializerOptions

序列化模板参数时要使用的序列化选项。

options RequestOptions

发送请求时要使用的选项。

Returns

Task<Cacheable<IUserMessage, Guid>>

一个表示异步发送操作的任务。任务的结果包含所发送消息的可延迟加载的消息对象。

Type Parameters

T

参数的类型。

ToString()

获取此参与到此私聊频道的另外一位用户的包含 @ 前缀的用户名及识别号格式化字符串。

public override string ToString()

Returns

string

一个表示此私聊频道的格式化字符串。

See Also

UsernameAndIdentifyNumber(IUser, bool)

UpdateAsync(RequestOptions?)

通过 REST API 获取此实体对象的最新状态，并替换当前对象的属性。

public override Task UpdateAsync(RequestOptions? options = null)

Parameters

options RequestOptions

发送请求时要使用的选项。

Returns

Task

一个表示异步更新操作的任务。

Remarks

warning

此方法将从 KOOK REST API 获取最新数据，并替换当前对象的属性，而非使用指定的属性修改 KOOK 服务端的数据。