@@ -2209,6 +2209,378 @@ URL {
2209
2209
}
2210
2210
```
2211
2211
2212
+ ## Class: ` http.OutgoingMessage `
2213
+ <!-- YAML
2214
+ added: v0.1.17
2215
+ -->
2216
+
2217
+ * Extends: {Stream}
2218
+
2219
+ This class serves as the parent class of [ ` http.ClientRequest ` ] [ ]
2220
+ and [ ` http.ServerResponse ` ] [ ] . It is an abstract of outgoing message from
2221
+ the perspective of the participants of HTTP transaction.
2222
+
2223
+ ### Event: ` drain `
2224
+ <!-- YAML
2225
+ added: v0.3.6
2226
+ -->
2227
+
2228
+ Emitted when the buffer of the message is free again.
2229
+
2230
+ ### Event: ` finish `
2231
+ <!-- YAML
2232
+ added: v0.1.17
2233
+ -->
2234
+
2235
+ Emitted when transmission is finished successfully.
2236
+
2237
+ ### Event: ` prefinish `
2238
+ <!-- YAML
2239
+ added: v0.11.6
2240
+ -->
2241
+
2242
+ Emitted when ` outgoingMessage.end ` was called.
2243
+ When the event is emitted, all data has been processed but not necessarily
2244
+ completely flushed.
2245
+
2246
+ ### ` outgoingMessage.addTrailers(headers) `
2247
+ <!-- YAML
2248
+ added: v0.3.0
2249
+ -->
2250
+
2251
+ * ` headers ` {Object}
2252
+
2253
+ Adds HTTP trailers (headers but at the end of the message) to the message.
2254
+
2255
+ Trailers are ** only** be emitted if the message is chunked encoded. If not,
2256
+ trailer will be silently discarded.
2257
+
2258
+ HTTP requires the ` Trailer ` header to be sent in order to emit trailers,
2259
+ with a list of header fields in its value, e.g.
2260
+
2261
+ ``` js
2262
+ message .writeHead (200 , { ' Content-Type' : ' text/plain' ,
2263
+ ' Trailer' : ' Content-MD5' });
2264
+ message .write (fileData);
2265
+ message .addTrailers ({ ' Content-MD5' : ' 7895bf4b8828b55ceaf47747b4bca667' });
2266
+ message .end ();
2267
+ ```
2268
+
2269
+ Attempting to set a header field name or value that contains invalid characters
2270
+ will result in a ` TypeError ` being thrown.
2271
+
2272
+ ### ` outgoingMessage.connection `
2273
+ <!-- YAML
2274
+ added: v0.3.0
2275
+ deprecated: REPLACEME
2276
+ -->
2277
+
2278
+ > Stability: 0 - Deprecated: Use [ ` outgoingMessage.socket ` ] [ ] instead.
2279
+
2280
+ Aliases of ` outgoingMessage.socket `
2281
+ ### ` outgoingMessage.cork() `
2282
+ <!-- YAML
2283
+ added: v14.0.0
2284
+ -->
2285
+
2286
+ See [ ` writable.cork() ` ] [ ] .
2287
+
2288
+ ### ` outgoingMessage.destroy([error]) `
2289
+ <!-- YAML
2290
+ added: v0.3.0
2291
+ -->
2292
+
2293
+ * ` error ` {Error} Optional, an error to emit with ` error ` event
2294
+ * Returns: {this}
2295
+
2296
+ Destroys the message. Once a socket is associated with the message
2297
+ and is connected, that socket will be destroyed as well.
2298
+
2299
+ ### ` outgoingMessage.end(chunk[, encoding][, callback]) `
2300
+ <!-- YAML
2301
+ added: v0.1.90
2302
+ changes:
2303
+ - version: v0.11.6
2304
+ description: add `callback` argument.
2305
+ -->
2306
+
2307
+ * ` chunk ` {string | Buffer}
2308
+ * ` encoding ` {string} Optional, ** Default** : ` utf-8 `
2309
+ * ` callback ` {Function} Optional
2310
+ * Returns: {this}
2311
+
2312
+ Finishes the outgoing message. If any parts of the body are unsent, it will
2313
+ flush them to the underlying system. If the message is chunked, it will
2314
+ send the terminating chunk ` 0\r\n\r\n ` , and send the trailer (if any).
2315
+
2316
+ If ` chunk ` is specified, it is equivalent to call
2317
+ ` outgoingMessage.write(chunk, encoding) ` , followed by
2318
+ ` outgoingMessage.end(callback) ` .
2319
+
2320
+ If ` callback ` is provided, it will be called when the message is finished.
2321
+ (equivalent to the callback to event ` finish ` )
2322
+
2323
+ ### ` outgoingMessage.flushHeaders() `
2324
+ <!-- YAML
2325
+ added: v1.6.0
2326
+ -->
2327
+
2328
+ Compulsorily flushes the message headers
2329
+
2330
+ For efficiency reason, Node.js normally buffers the message headers
2331
+ until ` outgoingMessage.end() ` is called or the first chunk of message data
2332
+ is written. It then tries to pack the headers and data into a single TCP
2333
+ packet.
2334
+
2335
+ It is usually desired (it saves a TCP round-trip), but not when the first
2336
+ data is not sent until possibly much later. ` outgoingMessage.flushHeaders() `
2337
+ bypasses the optimization and kickstarts the request.
2338
+
2339
+ ### ` outgoingMessage.getHeader(name) `
2340
+ <!-- YAML
2341
+ added: v0.4.0
2342
+ -->
2343
+
2344
+ * ` name ` {string} Name of header
2345
+ * Returns {string | undefined}
2346
+
2347
+ Gets value of HTTP header with given name. If such name doesn't exist in
2348
+ message, it will be ` undefined ` .
2349
+
2350
+ ### ` outgoingMessage.getHeaderNames() `
2351
+ <!-- YAML
2352
+ added: v8.0.0
2353
+ -->
2354
+
2355
+ * Returns {string[ ] }
2356
+
2357
+ Returns an array of names of headers of the outgoing outgoingMessage. All
2358
+ names are lowercase.
2359
+
2360
+ ### ` outgoingMessage.getHeaders() `
2361
+ <!-- YAML
2362
+ added: v8.0.0
2363
+ -->
2364
+
2365
+ * Returns: {Object}
2366
+
2367
+ Returns a shallow copy of the current outgoing headers. Since a shallow
2368
+ copy is used, array values may be mutated without additional calls to
2369
+ various header-related http module methods. The keys of the returned
2370
+ object are the header names and the values are the respective header
2371
+ values. All header names are lowercase.
2372
+
2373
+ The object returned by the ` outgoingMessage.getHeaders() ` method does
2374
+ not prototypically inherit from the JavaScript Object. This means that
2375
+ typical Object methods such as ` obj.toString() ` , ` obj.hasOwnProperty() ` ,
2376
+ and others are not defined and will not work.
2377
+
2378
+ ``` js
2379
+ outgoingMessage .setHeader (' Foo' , ' bar' );
2380
+ outgoingMessage .setHeader (' Set-Cookie' , [' foo=bar' , ' bar=baz' ]);
2381
+
2382
+ const headers = outgoingMessage .getHeaders ();
2383
+ // headers === { foo: 'bar', 'set-cookie': ['foo=bar', 'bar=baz'] }
2384
+ ```
2385
+
2386
+ ### ` outgoingMessage.hasHeader(name) `
2387
+ <!-- YAML
2388
+ added: v8.0.0
2389
+ -->
2390
+
2391
+ * ` name ` {string}
2392
+ * Returns {boolean}
2393
+
2394
+ Returns ` true ` if the header identified by ` name ` is currently set in the
2395
+ outgoing headers. The header name is case-insensitive.
2396
+
2397
+ ``` js
2398
+ const hasContentType = outgoingMessage .hasHeader (' content-type' );
2399
+ ```
2400
+
2401
+ ### ` outgoingMessage.headersSent `
2402
+ <!-- YAML
2403
+ added: v0.9.3
2404
+ -->
2405
+
2406
+ * {boolean}
2407
+
2408
+ Read-only. ` true ` if the headers were sent, otherwise ` false ` .
2409
+
2410
+ ### ` outgoingMessage.pipe() `
2411
+ <!-- YAML
2412
+ added: v9.0.0
2413
+ -->
2414
+
2415
+ Overrides the pipe method of legacy ` Stream ` which is the parent class of
2416
+ ` http.outgoingMessage ` .
2417
+
2418
+ Since ` OutgoingMessage ` should be a write-only stream,
2419
+ call this function will throw an ` Error ` . Thus, it disabled the pipe method
2420
+ it inherits from ` Stream ` .
2421
+
2422
+ User should not call this function directly.
2423
+
2424
+ ### ` outgoingMessage.removeHeader() `
2425
+ <!-- YAML
2426
+ added: v0.4.0
2427
+ -->
2428
+
2429
+ Removes a header that is queued for implicit sending.
2430
+
2431
+ ``` js
2432
+ outgoingMessage .removeHeader (' Content-Encoding' );
2433
+ ```
2434
+
2435
+ ### ` outgoingMessage.setHeader(name, value) `
2436
+ <!-- YAML
2437
+ added: v0.4.0
2438
+ -->
2439
+
2440
+ * ` name ` {string} Header name
2441
+ * ` value ` {string} Header value
2442
+ * Returns: {this}
2443
+
2444
+ Sets a single header value for header object.
2445
+
2446
+ ### ` outgoingMessage.setTimeout(msesc[, callback]) `
2447
+ <!-- YAML
2448
+ added: v0.9.12
2449
+ -->
2450
+
2451
+ * ` msesc ` {number}
2452
+ * ` callback ` {Function} Optional function to be called when a timeout
2453
+ occurs, Same as binding to the ` timeout ` event.
2454
+ * Returns: {this}
2455
+
2456
+ Once a socket is associated with the message and is connected,
2457
+ [ ` socket.setTimeout() ` ] [ ] will be called with ` msecs ` as the first parameter.
2458
+
2459
+ ### ` outgoingMessage.socket `
2460
+ <!-- YAML
2461
+ added: v0.3.0
2462
+ -->
2463
+
2464
+ * {stream.Duplex}
2465
+
2466
+ Reference to the underlying socket. Usually users will not want to access
2467
+ this property.
2468
+
2469
+ After calling ` outgoingMessage.end() ` , this property will be nulled.
2470
+
2471
+ ### ` outgoingMessage.uncork() `
2472
+ <!-- YAML
2473
+ added: v14.0.0
2474
+ -->
2475
+
2476
+ See [ ` writable.uncork() ` ] [ ]
2477
+
2478
+ ### ` outgoingMessage.writableCorked `
2479
+ <!-- YAML
2480
+ added: v14.0.0
2481
+ -->
2482
+
2483
+ * {number}
2484
+
2485
+ This ` outgoingMessage.writableCorked ` will return the time how many
2486
+ ` outgoingMessage.cork() ` have been called.
2487
+
2488
+ ### ` outgoingMessage.writableEnded `
2489
+ <!-- YAML
2490
+ added: v13.0.0
2491
+ -->
2492
+
2493
+ * {boolean}
2494
+
2495
+ Readonly, ` true ` if ` outgoingMessage.end() ` has been called. Noted that
2496
+ this property does not reflect whether the data has been flush. For that
2497
+ purpose, use ` message.writableFinished ` instead.
2498
+
2499
+ ### ` outgoingMessage.writableFinished `
2500
+ <!-- YAML
2501
+ added: v13.0.0
2502
+ -->
2503
+
2504
+ * {boolean}
2505
+
2506
+ Readonly. ` true ` if all data has been flushed to the underlying system.
2507
+
2508
+ ### ` outgoingMessage.writableHighWaterMark `
2509
+ <!-- YAML
2510
+ added: v13.0.0
2511
+ -->
2512
+
2513
+ * {number}
2514
+
2515
+ This ` outgoingMessage.writableHighWaterMark ` will be the ` highWaterMark ` of
2516
+ underlying socket if socket exists. Else, it would be the default
2517
+ ` highWaterMark ` .
2518
+
2519
+ ` highWaterMark ` is the maximum amount of data which can be potentially
2520
+ buffered by socket.
2521
+
2522
+ ### ` outgoingMessage.writableLength `
2523
+ <!-- YAML
2524
+ added: v13.0.0
2525
+ -->
2526
+
2527
+ * {number}
2528
+
2529
+ Readonly, This ` outgoingMessage.writableLength ` contains the number of
2530
+ bytes (or objects) in the buffer ready to send.
2531
+
2532
+ ### ` outgoingMessage.writableObjectMode `
2533
+ <!-- YAML
2534
+ added: v13.0.0
2535
+ -->
2536
+
2537
+ * {boolean}
2538
+
2539
+ Readonly, always returns ` false ` .
2540
+
2541
+ ### ` outgoingMessage.write(chunk[, encoding][, callback]) `
2542
+ <!-- YAML
2543
+ added: v0.1.29
2544
+ changes:
2545
+ - version: v0.11.6
2546
+ description: add `callback` argument.
2547
+ -->
2548
+
2549
+ * ` chunk ` {string | Buffer}
2550
+ * ` encoding ` {string} ** Default** : ` utf-8 `
2551
+ * ` callback ` {Function}
2552
+ * Returns {boolean}
2553
+
2554
+ If this method is called and header is not sent, it will call
2555
+ ` this._implicitHeader ` to flush implicit header.
2556
+ If the message should not have a body (indicated by ` this._hasBody ` ),
2557
+ the call is ignored and ` chunk ` will not be sent. It could be useful
2558
+ when handling particular message which must not include a body.
2559
+ e.g. response to ` HEAD ` request, ` 204 ` and ` 304 ` response.
2560
+
2561
+ ` chunk ` can be a string or a buffer. When ` chunk ` is a string, the
2562
+ ` encoding ` parameter specifies how to encode ` chunk ` into a byte stream.
2563
+ ` callback ` will be called when the ` chunk ` is flushed.
2564
+
2565
+ If the message is transferred in chucked encoding
2566
+ (indicated by ` this.chunkedEncoding ` ), ` chunk ` will be flushed as
2567
+ one chunk among a stream of chunks. Otherwise, it will be flushed as body
2568
+ of message.
2569
+
2570
+ This method handles the raw body of HTTP message and has nothing to do with
2571
+ higher-level multi-part body encodings that may be used.
2572
+
2573
+ If it is the first call to this method of a message, it will send the
2574
+ buffered header first, then flush the the ` chunk ` as described above.
2575
+
2576
+ The second and successive calls to this method, it will assume the data
2577
+ will streamed and send the new data separately. It means that the response
2578
+ is buffered up to the first chunk of the body.
2579
+
2580
+ Returns ` true ` if the entire data was flushed successfully to the kernel
2581
+ buffer. Returns ` false ` if all or part of the data was queued in user
2582
+ memory. Event ` drain ` will be emitted when the buffer is free again.
2583
+
2212
2584
## ` http.METHODS `
2213
2585
<!-- YAML
2214
2586
added: v0.11.8
@@ -2734,6 +3106,7 @@ try {
2734
3106
[ `http.ClientRequest` ] : #http_class_http_clientrequest
2735
3107
[ `http.IncomingMessage` ] : #http_class_http_incomingmessage
2736
3108
[ `http.Server` ] : #http_class_http_server
3109
+ [ `http.ServerResponse` ] : #http_class_http_serverresponse
2737
3110
[ `http.get()` ] : #http_http_get_options_callback
2738
3111
[ `http.globalAgent` ] : #http_http_globalagent
2739
3112
[ `http.request()` ] : #http_http_request_options_callback
@@ -2743,6 +3116,7 @@ try {
2743
3116
[ `net.Socket` ] : net.md#net_class_net_socket
2744
3117
[ `net.createConnection()` ] : net.md#net_net_createconnection_options_connectlistener
2745
3118
[ `new URL()` ] : url.md#url_new_url_input_base
3119
+ [ `outgoingMessage.socket` ] : #http_outgoingMessage.socket
2746
3120
[ `removeHeader(name)` ] : #http_request_removeheader_name
2747
3121
[ `request.end()` ] : #http_request_end_data_encoding_callback
2748
3122
[ `request.destroy()` ] : #http_request_destroy_error
0 commit comments