wasapi: Rename struct element for device name
[platform/upstream/gstreamer.git] / sys / wasapi / gstwasapisrc.c
1 /*
2  * Copyright (C) 2008 Ole André Vadla Ravnås <ole.andre.ravnas@tandberg.com>
3  * Copyright (C) 2018 Centricular Ltd.
4  *   Author: Nirbheek Chauhan <nirbheek@centricular.com>
5  *
6  * This library is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Library General Public
8  * License as published by the Free Software Foundation; either
9  * version 2 of the License, or (at your option) any later version.
10  *
11  * This library is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14  * Library General Public License for more details.
15  *
16  * You should have received a copy of the GNU Library General Public
17  * License along with this library; if not, write to the
18  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
19  * Boston, MA 02110-1301, USA.
20  */
21
22 /**
23  * SECTION:element-wasapisrc
24  * @title: wasapisrc
25  *
26  * Provides audio capture from the Windows Audio Session API available with
27  * Vista and newer.
28  *
29  * ## Example pipelines
30  * |[
31  * gst-launch-1.0 -v wasapisrc ! fakesink
32  * ]| Capture from the default audio device and render to fakesink.
33  *
34  */
35 #ifdef HAVE_CONFIG_H
36 #  include <config.h>
37 #endif
38
39 #include "gstwasapisrc.h"
40
41 #include <mmdeviceapi.h>
42
43 GST_DEBUG_CATEGORY_STATIC (gst_wasapi_src_debug);
44 #define GST_CAT_DEFAULT gst_wasapi_src_debug
45
46 static GstStaticPadTemplate src_template = GST_STATIC_PAD_TEMPLATE ("src",
47     GST_PAD_SRC,
48     GST_PAD_ALWAYS,
49     GST_STATIC_CAPS (GST_WASAPI_STATIC_CAPS));
50
51 #define DEFAULT_ROLE    GST_WASAPI_DEVICE_ROLE_CONSOLE
52
53 enum
54 {
55   PROP_0,
56   PROP_ROLE,
57   PROP_DEVICE
58 };
59
60 static void gst_wasapi_src_dispose (GObject * object);
61 static void gst_wasapi_src_finalize (GObject * object);
62 static void gst_wasapi_src_set_property (GObject * object, guint prop_id,
63     const GValue * value, GParamSpec * pspec);
64 static void gst_wasapi_src_get_property (GObject * object, guint prop_id,
65     GValue * value, GParamSpec * pspec);
66
67 static GstCaps *gst_wasapi_src_get_caps (GstBaseSrc * bsrc, GstCaps * filter);
68
69 static gboolean gst_wasapi_src_open (GstAudioSrc * asrc);
70 static gboolean gst_wasapi_src_close (GstAudioSrc * asrc);
71 static gboolean gst_wasapi_src_prepare (GstAudioSrc * asrc,
72     GstAudioRingBufferSpec * spec);
73 static gboolean gst_wasapi_src_unprepare (GstAudioSrc * asrc);
74 static guint gst_wasapi_src_read (GstAudioSrc * asrc, gpointer data,
75     guint length, GstClockTime * timestamp);
76 static guint gst_wasapi_src_delay (GstAudioSrc * asrc);
77 static void gst_wasapi_src_reset (GstAudioSrc * asrc);
78
79 static GstClockTime gst_wasapi_src_get_time (GstClock * clock,
80     gpointer user_data);
81
82 #define gst_wasapi_src_parent_class parent_class
83 G_DEFINE_TYPE (GstWasapiSrc, gst_wasapi_src, GST_TYPE_AUDIO_SRC);
84
85 static void
86 gst_wasapi_src_class_init (GstWasapiSrcClass * klass)
87 {
88   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
89   GstElementClass *gstelement_class = GST_ELEMENT_CLASS (klass);
90   GstBaseSrcClass *gstbasesrc_class = GST_BASE_SRC_CLASS (klass);
91   GstAudioSrcClass *gstaudiosrc_class = GST_AUDIO_SRC_CLASS (klass);
92
93   gobject_class->dispose = gst_wasapi_src_dispose;
94   gobject_class->finalize = gst_wasapi_src_finalize;
95   gobject_class->set_property = gst_wasapi_src_set_property;
96   gobject_class->get_property = gst_wasapi_src_get_property;
97
98   g_object_class_install_property (gobject_class,
99       PROP_ROLE,
100       g_param_spec_enum ("role", "Role",
101           "Role of the device: communications, multimedia, etc",
102           GST_WASAPI_DEVICE_TYPE_ROLE, DEFAULT_ROLE, G_PARAM_READWRITE |
103           G_PARAM_STATIC_STRINGS | GST_PARAM_MUTABLE_READY));
104
105   g_object_class_install_property (gobject_class,
106       PROP_DEVICE,
107       g_param_spec_string ("device", "Device",
108           "WASAPI playback device as a GUID string",
109           NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
110
111   gst_element_class_add_static_pad_template (gstelement_class, &src_template);
112   gst_element_class_set_static_metadata (gstelement_class, "WasapiSrc",
113       "Source/Audio",
114       "Stream audio from an audio capture device through WASAPI",
115       "Ole André Vadla Ravnås <ole.andre.ravnas@tandberg.com>");
116
117   gstbasesrc_class->get_caps = GST_DEBUG_FUNCPTR (gst_wasapi_src_get_caps);
118
119   gstaudiosrc_class->open = GST_DEBUG_FUNCPTR (gst_wasapi_src_open);
120   gstaudiosrc_class->close = GST_DEBUG_FUNCPTR (gst_wasapi_src_close);
121   gstaudiosrc_class->read = GST_DEBUG_FUNCPTR (gst_wasapi_src_read);
122   gstaudiosrc_class->prepare = GST_DEBUG_FUNCPTR (gst_wasapi_src_prepare);
123   gstaudiosrc_class->unprepare = GST_DEBUG_FUNCPTR (gst_wasapi_src_unprepare);
124   gstaudiosrc_class->delay = GST_DEBUG_FUNCPTR (gst_wasapi_src_delay);
125   gstaudiosrc_class->reset = GST_DEBUG_FUNCPTR (gst_wasapi_src_reset);
126
127   GST_DEBUG_CATEGORY_INIT (gst_wasapi_src_debug, "wasapisrc",
128       0, "Windows audio session API source");
129 }
130
131 static void
132 gst_wasapi_src_init (GstWasapiSrc * self)
133 {
134   /* override with a custom clock */
135   if (GST_AUDIO_BASE_SRC (self)->clock)
136     gst_object_unref (GST_AUDIO_BASE_SRC (self)->clock);
137
138   GST_AUDIO_BASE_SRC (self)->clock = gst_audio_clock_new ("GstWasapiSrcClock",
139       gst_wasapi_src_get_time, gst_object_ref (self),
140       (GDestroyNotify) gst_object_unref);
141
142   self->event_handle = CreateEvent (NULL, FALSE, FALSE, NULL);
143
144   CoInitialize (NULL);
145 }
146
147 static void
148 gst_wasapi_src_dispose (GObject * object)
149 {
150   GstWasapiSrc *self = GST_WASAPI_SRC (object);
151
152   if (self->event_handle != NULL) {
153     CloseHandle (self->event_handle);
154     self->event_handle = NULL;
155   }
156
157   if (self->client_clock != NULL) {
158     IUnknown_Release (self->client_clock);
159     self->client_clock = NULL;
160   }
161
162   if (self->client != NULL) {
163     IUnknown_Release (self->client);
164     self->client = NULL;
165   }
166
167   if (self->capture_client != NULL) {
168     IUnknown_Release (self->capture_client);
169     self->capture_client = NULL;
170   }
171
172   G_OBJECT_CLASS (parent_class)->dispose (object);
173 }
174
175 static void
176 gst_wasapi_src_finalize (GObject * object)
177 {
178   GstWasapiSrc *self = GST_WASAPI_SRC (object);
179
180   g_clear_pointer (&self->mix_format, CoTaskMemFree);
181
182   CoUninitialize ();
183
184   g_clear_pointer (&self->cached_caps, gst_caps_unref);
185   g_clear_pointer (&self->positions, g_free);
186   g_clear_pointer (&self->device_strid, g_free);
187
188   G_OBJECT_CLASS (parent_class)->finalize (object);
189 }
190
191 static void
192 gst_wasapi_src_set_property (GObject * object, guint prop_id,
193     const GValue * value, GParamSpec * pspec)
194 {
195   GstWasapiSrc *self = GST_WASAPI_SRC (object);
196
197   switch (prop_id) {
198     case PROP_ROLE:
199       self->role = gst_wasapi_device_role_to_erole (g_value_get_enum (value));
200       break;
201     case PROP_DEVICE:
202     {
203       const gchar *device = g_value_get_string (value);
204       g_free (self->device_strid);
205       self->device_strid =
206           device ? g_utf8_to_utf16 (device, -1, NULL, NULL, NULL) : NULL;
207       break;
208     }
209     default:
210       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
211       break;
212   }
213 }
214
215 static void
216 gst_wasapi_src_get_property (GObject * object, guint prop_id,
217     GValue * value, GParamSpec * pspec)
218 {
219   GstWasapiSrc *self = GST_WASAPI_SRC (object);
220
221   switch (prop_id) {
222     case PROP_ROLE:
223       g_value_set_enum (value, gst_wasapi_erole_to_device_role (self->role));
224       break;
225     case PROP_DEVICE:
226       g_value_take_string (value, self->device_strid ?
227           g_utf16_to_utf8 (self->device_strid, -1, NULL, NULL, NULL) : NULL);
228       break;
229     default:
230       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
231       break;
232   }
233 }
234
235 static GstCaps *
236 gst_wasapi_src_get_caps (GstBaseSrc * bsrc, GstCaps * filter)
237 {
238   GstWasapiSrc *self = GST_WASAPI_SRC (bsrc);
239   WAVEFORMATEX *format = NULL;
240   GstCaps *caps = NULL;
241   HRESULT hr;
242
243   GST_DEBUG_OBJECT (self, "entering get caps");
244
245   if (self->cached_caps) {
246     caps = gst_caps_ref (self->cached_caps);
247   } else {
248     GstCaps *template_caps;
249
250     template_caps = gst_pad_get_pad_template_caps (bsrc->srcpad);
251
252     if (!self->client)
253       gst_wasapi_src_open (GST_AUDIO_SRC (bsrc));
254
255     hr = IAudioClient_GetMixFormat (self->client, &format);
256     if (hr != S_OK || format == NULL) {
257       GST_ELEMENT_ERROR (self, STREAM, FORMAT, (NULL),
258           ("GetMixFormat failed: %s", gst_wasapi_util_hresult_to_string (hr)));
259       goto out;
260     }
261
262     gst_wasapi_util_parse_waveformatex ((WAVEFORMATEXTENSIBLE *) format,
263         template_caps, &caps, &self->positions);
264     if (caps == NULL) {
265       GST_ELEMENT_ERROR (self, STREAM, FORMAT, (NULL), ("unknown format"));
266       goto out;
267     }
268
269     {
270       gchar *pos_str = gst_audio_channel_positions_to_string (self->positions,
271           format->nChannels);
272       GST_INFO_OBJECT (self, "positions are: %s", pos_str);
273       g_free (pos_str);
274     }
275
276     self->mix_format = format;
277     gst_caps_replace (&self->cached_caps, caps);
278     gst_caps_unref (template_caps);
279   }
280
281   if (filter) {
282     GstCaps *filtered =
283         gst_caps_intersect_full (filter, caps, GST_CAPS_INTERSECT_FIRST);
284     gst_caps_unref (caps);
285     caps = filtered;
286   }
287
288   GST_DEBUG_OBJECT (self, "returning caps %" GST_PTR_FORMAT, caps);
289
290 out:
291   return caps;
292 }
293
294 static gboolean
295 gst_wasapi_src_open (GstAudioSrc * asrc)
296 {
297   GstWasapiSrc *self = GST_WASAPI_SRC (asrc);
298   gboolean res = FALSE;
299   IAudioClient *client = NULL;
300
301   if (self->client)
302     return TRUE;
303
304   /* FIXME: Switching the default device does not switch the stream to it,
305    * even if the old device was unplugged. We need to handle this somehow.
306    * For example, perhaps we should automatically switch to the new device if
307    * the default device is changed and a device isn't explicitly selected. */
308   if (!gst_wasapi_util_get_device_client (GST_ELEMENT (self), TRUE,
309           self->role, self->device_strid, &client)) {
310     if (!self->device_strid)
311       GST_ELEMENT_ERROR (self, RESOURCE, OPEN_READ, (NULL),
312           ("Failed to get default device"));
313     else
314       GST_ELEMENT_ERROR (self, RESOURCE, OPEN_READ, (NULL),
315           ("Failed to open device %S", self->device_strid));
316     goto beach;
317   }
318
319   self->client = client;
320   res = TRUE;
321
322 beach:
323
324   return res;
325 }
326
327 static gboolean
328 gst_wasapi_src_close (GstAudioSrc * asrc)
329 {
330   GstWasapiSrc *self = GST_WASAPI_SRC (asrc);
331
332   if (self->client != NULL) {
333     IUnknown_Release (self->client);
334     self->client = NULL;
335   }
336
337   return TRUE;
338 }
339
340 static gboolean
341 gst_wasapi_src_prepare (GstAudioSrc * asrc, GstAudioRingBufferSpec * spec)
342 {
343   GstWasapiSrc *self = GST_WASAPI_SRC (asrc);
344   gboolean res = FALSE;
345   IAudioClock *client_clock = NULL;
346   guint64 client_clock_freq = 0;
347   IAudioCaptureClient *capture_client = NULL;
348   REFERENCE_TIME latency_rt;
349   gint64 default_period, min_period;
350   guint bpf, rate, buffer_frames;
351   HRESULT hr;
352
353   hr = IAudioClient_GetDevicePeriod (self->client, &default_period,
354       &min_period);
355   if (hr != S_OK) {
356     GST_ERROR_OBJECT (self, "IAudioClient::GetDevicePeriod failed");
357     goto beach;
358   }
359   GST_INFO_OBJECT (self, "wasapi default period: %" G_GINT64_FORMAT
360       ", min period: %" G_GINT64_FORMAT, default_period, min_period);
361
362   /* Set hnsBufferDuration to 0, which should, in theory, tell the device to
363    * create a buffer with the smallest latency possible. In practice, this is
364    * usually 2 * default_period. See:
365    * https://msdn.microsoft.com/en-us/library/windows/desktop/dd370871(v=vs.85).aspx
366    *
367    * NOTE: min_period is a lie, and I have never seen WASAPI use it as the
368    * current period */
369   hr = IAudioClient_Initialize (self->client, AUDCLNT_SHAREMODE_SHARED,
370       AUDCLNT_STREAMFLAGS_EVENTCALLBACK, 0, 0, self->mix_format, NULL);
371   if (hr != S_OK) {
372     GST_ELEMENT_ERROR (self, RESOURCE, OPEN_READ, (NULL),
373         ("IAudioClient::Initialize failed: %s",
374             gst_wasapi_util_hresult_to_string (hr)));
375     goto beach;
376   }
377
378   /* Total size in frames of the allocated buffer that we will read from */
379   hr = IAudioClient_GetBufferSize (self->client, &buffer_frames);
380   if (hr != S_OK) {
381     GST_ERROR_OBJECT (self, "IAudioClient::GetBufferSize failed");
382     goto beach;
383   }
384
385   bpf = GST_AUDIO_INFO_BPF (&spec->info);
386   rate = GST_AUDIO_INFO_RATE (&spec->info);
387   GST_INFO_OBJECT (self, "buffer size is %i frames, bpf is %i bytes, "
388       "rate is %i Hz", buffer_frames, bpf, rate);
389
390   spec->segsize = gst_util_uint64_scale_int_round (rate * bpf,
391       default_period * 100, GST_SECOND);
392   spec->segtotal = (buffer_frames * bpf) / spec->segsize;
393
394   GST_INFO_OBJECT (self, "segsize is %i, segtotal is %i", spec->segsize,
395       spec->segtotal);
396
397   /* Get WASAPI latency for logging */
398   hr = IAudioClient_GetStreamLatency (self->client, &latency_rt);
399   if (hr != S_OK) {
400     GST_ERROR_OBJECT (self, "IAudioClient::GetStreamLatency failed");
401     goto beach;
402   }
403   GST_INFO_OBJECT (self, "wasapi stream latency: %" G_GINT64_FORMAT " (%"
404       G_GINT64_FORMAT " ms)", latency_rt, latency_rt / 10000);
405
406   /* Set the event handler which will trigger reads */
407   hr = IAudioClient_SetEventHandle (self->client, self->event_handle);
408   if (hr != S_OK) {
409     GST_ERROR_OBJECT (self, "IAudioClient::SetEventHandle failed");
410     goto beach;
411   }
412
413   /* Get the clock and the clock freq */
414   if (!gst_wasapi_util_get_clock (GST_ELEMENT (self), self->client,
415           &client_clock)) {
416     goto beach;
417   }
418
419   hr = IAudioClock_GetFrequency (client_clock, &client_clock_freq);
420   if (hr != S_OK) {
421     GST_ERROR_OBJECT (self, "IAudioClock::GetFrequency failed");
422     goto beach;
423   }
424
425   /* Get capture source client and start it up */
426   if (!gst_wasapi_util_get_capture_client (GST_ELEMENT (self), self->client,
427           &capture_client)) {
428     goto beach;
429   }
430
431   hr = IAudioClient_Start (self->client);
432   if (hr != S_OK) {
433     GST_ERROR_OBJECT (self, "IAudioClient::Start failed");
434     goto beach;
435   }
436
437   self->client_clock = client_clock;
438   self->client_clock_freq = client_clock_freq;
439   self->capture_client = capture_client;
440
441   gst_audio_ring_buffer_set_channel_positions (GST_AUDIO_BASE_SRC
442       (self)->ringbuffer, self->positions);
443
444   res = TRUE;
445
446 beach:
447   if (!res) {
448     if (capture_client != NULL)
449       IUnknown_Release (capture_client);
450
451     if (client_clock != NULL)
452       IUnknown_Release (client_clock);
453   }
454
455   return res;
456 }
457
458 static gboolean
459 gst_wasapi_src_unprepare (GstAudioSrc * asrc)
460 {
461   GstWasapiSrc *self = GST_WASAPI_SRC (asrc);
462
463   if (self->client != NULL) {
464     IAudioClient_Stop (self->client);
465   }
466
467   if (self->capture_client != NULL) {
468     IUnknown_Release (self->capture_client);
469     self->capture_client = NULL;
470   }
471
472   if (self->client_clock != NULL) {
473     IUnknown_Release (self->client_clock);
474     self->client_clock = NULL;
475   }
476
477   return TRUE;
478 }
479
480 static guint
481 gst_wasapi_src_read (GstAudioSrc * asrc, gpointer data, guint length,
482     GstClockTime * timestamp)
483 {
484   GstWasapiSrc *self = GST_WASAPI_SRC (asrc);
485   HRESULT hr;
486   gint16 *from = NULL;
487   guint wanted = length;
488   DWORD flags;
489
490   while (wanted > 0) {
491     guint have_frames, n_frames, want_frames, read_len;
492
493     /* Wait for data to become available */
494     WaitForSingleObject (self->event_handle, INFINITE);
495
496     hr = IAudioCaptureClient_GetBuffer (self->capture_client,
497         (BYTE **) & from, &have_frames, &flags, NULL, NULL);
498     if (hr != S_OK) {
499       if (hr == AUDCLNT_S_BUFFER_EMPTY)
500         GST_WARNING_OBJECT (self, "IAudioCaptureClient::GetBuffer failed: %s"
501             ", retrying", gst_wasapi_util_hresult_to_string (hr));
502       else
503         GST_ERROR_OBJECT (self, "IAudioCaptureClient::GetBuffer failed: %s",
504             gst_wasapi_util_hresult_to_string (hr));
505       length = 0;
506       goto beach;
507     }
508
509     if (flags != 0)
510       GST_INFO_OBJECT (self, "buffer flags=%#08x", (guint) flags);
511
512     /* XXX: How do we handle AUDCLNT_BUFFERFLAGS_SILENT? We're supposed to write
513      * out silence when that flag is set? See:
514      * https://msdn.microsoft.com/en-us/library/windows/desktop/dd370800(v=vs.85).aspx */
515
516     if (flags & AUDCLNT_BUFFERFLAGS_DATA_DISCONTINUITY)
517       GST_WARNING_OBJECT (self, "WASAPI reported glitch in buffer");
518
519     want_frames = wanted / self->mix_format->nBlockAlign;
520
521     /* If GetBuffer is returning more frames than we can handle, all we can do is
522      * hope that this is temporary and that things will settle down later. */
523     if (G_UNLIKELY (have_frames > want_frames))
524       GST_WARNING_OBJECT (self, "captured too many frames: have %i, want %i",
525           have_frames, want_frames);
526
527     /* Only copy data that will fit into the allocated buffer of size @length */
528     n_frames = MIN (have_frames, want_frames);
529     read_len = n_frames * self->mix_format->nBlockAlign;
530
531     {
532       guint bpf = self->mix_format->nBlockAlign;
533       GST_TRACE_OBJECT (self, "have: %i (%i bytes), can read: %i (%i bytes), "
534           "will read: %i (%i bytes)", have_frames, have_frames * bpf,
535           want_frames, wanted, n_frames, read_len);
536     }
537
538     memcpy (data, from, read_len);
539     wanted -= read_len;
540
541     /* Always release all captured buffers if we've captured any at all */
542     hr = IAudioCaptureClient_ReleaseBuffer (self->capture_client, have_frames);
543     if (hr != S_OK) {
544       GST_ERROR_OBJECT (self,
545           "IAudioCaptureClient::ReleaseBuffer () failed: %s",
546           gst_wasapi_util_hresult_to_string (hr));
547       goto beach;
548     }
549   }
550
551
552 beach:
553
554   return length;
555 }
556
557 static guint
558 gst_wasapi_src_delay (GstAudioSrc * asrc)
559 {
560   GstWasapiSrc *self = GST_WASAPI_SRC (asrc);
561   guint delay = 0;
562   HRESULT hr;
563
564   hr = IAudioClient_GetCurrentPadding (self->client, &delay);
565   if (hr != S_OK) {
566     GST_ELEMENT_ERROR (self, RESOURCE, READ, (NULL),
567         ("IAudioClient::GetCurrentPadding failed %s",
568             gst_wasapi_util_hresult_to_string (hr)));
569   }
570
571   return delay;
572 }
573
574 static void
575 gst_wasapi_src_reset (GstAudioSrc * asrc)
576 {
577   GstWasapiSrc *self = GST_WASAPI_SRC (asrc);
578   HRESULT hr;
579
580   if (self->client) {
581     hr = IAudioClient_Stop (self->client);
582     if (hr != S_OK) {
583       GST_ERROR_OBJECT (self, "IAudioClient::Stop () failed: %s",
584           gst_wasapi_util_hresult_to_string (hr));
585       return;
586     }
587
588     hr = IAudioClient_Reset (self->client);
589     if (hr != S_OK) {
590       GST_ERROR_OBJECT (self, "IAudioClient::Reset () failed: %s",
591           gst_wasapi_util_hresult_to_string (hr));
592       return;
593     }
594   }
595 }
596
597 static GstClockTime
598 gst_wasapi_src_get_time (GstClock * clock, gpointer user_data)
599 {
600   GstWasapiSrc *self = GST_WASAPI_SRC (user_data);
601   HRESULT hr;
602   guint64 devpos;
603   GstClockTime result;
604
605   if (G_UNLIKELY (self->client_clock == NULL))
606     return GST_CLOCK_TIME_NONE;
607
608   hr = IAudioClock_GetPosition (self->client_clock, &devpos, NULL);
609   if (G_UNLIKELY (hr != S_OK))
610     return GST_CLOCK_TIME_NONE;
611
612   result = gst_util_uint64_scale_int (devpos, GST_SECOND,
613       self->client_clock_freq);
614
615   /*
616      GST_DEBUG_OBJECT (self, "devpos = %" G_GUINT64_FORMAT
617      " frequency = %" G_GUINT64_FORMAT
618      " result = %" G_GUINT64_FORMAT " ms",
619      devpos, self->client_clock_freq, GST_TIME_AS_MSECONDS (result));
620    */
621
622   return result;
623 }