1 | // Copyright (c) .NET Foundation. All rights reserved.
|
2 | // Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
|
3 |
|
4 | import { ILogger } from "./ILogger";
|
5 | import { TransferFormat } from "./ITransport";
|
6 |
|
7 | /** Defines the type of a Hub Message. */
|
8 | export enum MessageType {
|
9 | /** Indicates the message is an Invocation message and implements the {@link @microsoft/signalr.InvocationMessage} interface. */
|
10 | Invocation = 1,
|
11 | /** Indicates the message is a StreamItem message and implements the {@link @microsoft/signalr.StreamItemMessage} interface. */
|
12 | StreamItem = 2,
|
13 | /** Indicates the message is a Completion message and implements the {@link @microsoft/signalr.CompletionMessage} interface. */
|
14 | Completion = 3,
|
15 | /** Indicates the message is a Stream Invocation message and implements the {@link @microsoft/signalr.StreamInvocationMessage} interface. */
|
16 | StreamInvocation = 4,
|
17 | /** Indicates the message is a Cancel Invocation message and implements the {@link @microsoft/signalr.CancelInvocationMessage} interface. */
|
18 | CancelInvocation = 5,
|
19 | /** Indicates the message is a Ping message and implements the {@link @microsoft/signalr.PingMessage} interface. */
|
20 | Ping = 6,
|
21 | /** Indicates the message is a Close message and implements the {@link @microsoft/signalr.CloseMessage} interface. */
|
22 | Close = 7,
|
23 | }
|
24 |
|
25 | /** Defines a dictionary of string keys and string values representing headers attached to a Hub message. */
|
26 | export interface MessageHeaders {
|
27 | /** Gets or sets the header with the specified key. */
|
28 | [key: string]: string;
|
29 | }
|
30 |
|
31 | /** Union type of all known Hub messages. */
|
32 | export type HubMessage =
|
33 | InvocationMessage |
|
34 | StreamInvocationMessage |
|
35 | StreamItemMessage |
|
36 | CompletionMessage |
|
37 | CancelInvocationMessage |
|
38 | PingMessage |
|
39 | CloseMessage;
|
40 |
|
41 | /** Defines properties common to all Hub messages. */
|
42 | export interface HubMessageBase {
|
43 | /** A {@link @microsoft/signalr.MessageType} value indicating the type of this message. */
|
44 | readonly type: MessageType;
|
45 | }
|
46 |
|
47 | /** Defines properties common to all Hub messages relating to a specific invocation. */
|
48 | export interface HubInvocationMessage extends HubMessageBase {
|
49 | /** A {@link @microsoft/signalr.MessageHeaders} dictionary containing headers attached to the message. */
|
50 | readonly headers?: MessageHeaders;
|
51 | /** The ID of the invocation relating to this message.
|
52 | *
|
53 | * This is expected to be present for {@link @microsoft/signalr.StreamInvocationMessage} and {@link @microsoft/signalr.CompletionMessage}. It may
|
54 | * be 'undefined' for an {@link @microsoft/signalr.InvocationMessage} if the sender does not expect a response.
|
55 | */
|
56 | readonly invocationId?: string;
|
57 | }
|
58 |
|
59 | /** A hub message representing a non-streaming invocation. */
|
60 | export interface InvocationMessage extends HubInvocationMessage {
|
61 | /** @inheritDoc */
|
62 | readonly type: MessageType.Invocation;
|
63 | /** The target method name. */
|
64 | readonly target: string;
|
65 | /** The target method arguments. */
|
66 | readonly arguments: any[];
|
67 | /** The target methods stream IDs. */
|
68 | readonly streamIds: string[];
|
69 | }
|
70 |
|
71 | /** A hub message representing a streaming invocation. */
|
72 | export interface StreamInvocationMessage extends HubInvocationMessage {
|
73 | /** @inheritDoc */
|
74 | readonly type: MessageType.StreamInvocation;
|
75 |
|
76 | /** The invocation ID. */
|
77 | readonly invocationId: string;
|
78 | /** The target method name. */
|
79 | readonly target: string;
|
80 | /** The target method arguments. */
|
81 | readonly arguments: any[];
|
82 | /** The target methods stream IDs. */
|
83 | readonly streamIds: string[];
|
84 | }
|
85 |
|
86 | /** A hub message representing a single item produced as part of a result stream. */
|
87 | export interface StreamItemMessage extends HubInvocationMessage {
|
88 | /** @inheritDoc */
|
89 | readonly type: MessageType.StreamItem;
|
90 |
|
91 | /** The invocation ID. */
|
92 | readonly invocationId: string;
|
93 |
|
94 | /** The item produced by the server. */
|
95 | readonly item?: any;
|
96 | }
|
97 |
|
98 | /** A hub message representing the result of an invocation. */
|
99 | export interface CompletionMessage extends HubInvocationMessage {
|
100 | /** @inheritDoc */
|
101 | readonly type: MessageType.Completion;
|
102 | /** The invocation ID. */
|
103 | readonly invocationId: string;
|
104 | /** The error produced by the invocation, if any.
|
105 | *
|
106 | * Either {@link @microsoft/signalr.CompletionMessage.error} or {@link @microsoft/signalr.CompletionMessage.result} must be defined, but not both.
|
107 | */
|
108 | readonly error?: string;
|
109 | /** The result produced by the invocation, if any.
|
110 | *
|
111 | * Either {@link @microsoft/signalr.CompletionMessage.error} or {@link @microsoft/signalr.CompletionMessage.result} must be defined, but not both.
|
112 | */
|
113 | readonly result?: any;
|
114 | }
|
115 |
|
116 | /** A hub message indicating that the sender is still active. */
|
117 | export interface PingMessage extends HubMessageBase {
|
118 | /** @inheritDoc */
|
119 | readonly type: MessageType.Ping;
|
120 | }
|
121 |
|
122 | /** A hub message indicating that the sender is closing the connection.
|
123 | *
|
124 | * If {@link @microsoft/signalr.CloseMessage.error} is defined, the sender is closing the connection due to an error.
|
125 | */
|
126 | export interface CloseMessage extends HubMessageBase {
|
127 | /** @inheritDoc */
|
128 | readonly type: MessageType.Close;
|
129 | /** The error that triggered the close, if any.
|
130 | *
|
131 | * If this property is undefined, the connection was closed normally and without error.
|
132 | */
|
133 | readonly error?: string;
|
134 |
|
135 | /** If true, clients with automatic reconnects enabled should attempt to reconnect after receiving the CloseMessage. Otherwise, they should not. */
|
136 | readonly allowReconnect?: boolean;
|
137 | }
|
138 |
|
139 | /** A hub message sent to request that a streaming invocation be canceled. */
|
140 | export interface CancelInvocationMessage extends HubInvocationMessage {
|
141 | /** @inheritDoc */
|
142 | readonly type: MessageType.CancelInvocation;
|
143 | /** The invocation ID. */
|
144 | readonly invocationId: string;
|
145 | }
|
146 |
|
147 | /** A protocol abstraction for communicating with SignalR Hubs. */
|
148 | export interface IHubProtocol {
|
149 | /** The name of the protocol. This is used by SignalR to resolve the protocol between the client and server. */
|
150 | readonly name: string;
|
151 | /** The version of the protocol. */
|
152 | readonly version: number;
|
153 | /** The {@link @microsoft/signalr.TransferFormat} of the protocol. */
|
154 | readonly transferFormat: TransferFormat;
|
155 |
|
156 | /** Creates an array of {@link @microsoft/signalr.HubMessage} objects from the specified serialized representation.
|
157 | *
|
158 | * If {@link @microsoft/signalr.IHubProtocol.transferFormat} is 'Text', the `input` parameter must be a string, otherwise it must be an ArrayBuffer.
|
159 | *
|
160 | * @param {string | ArrayBuffer | Buffer} input A string, ArrayBuffer, or Buffer containing the serialized representation.
|
161 | * @param {ILogger} logger A logger that will be used to log messages that occur during parsing.
|
162 | */
|
163 | parseMessages(input: string | ArrayBuffer | Buffer, logger: ILogger): HubMessage[];
|
164 |
|
165 | /** Writes the specified {@link @microsoft/signalr.HubMessage} to a string or ArrayBuffer and returns it.
|
166 | *
|
167 | * If {@link @microsoft/signalr.IHubProtocol.transferFormat} is 'Text', the result of this method will be a string, otherwise it will be an ArrayBuffer.
|
168 | *
|
169 | * @param {HubMessage} message The message to write.
|
170 | * @returns {string | ArrayBuffer} A string or ArrayBuffer containing the serialized representation of the message.
|
171 | */
|
172 | writeMessage(message: HubMessage): string | ArrayBuffer;
|
173 | }
|