?? func1_8q9f.htm
字號(hào):
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML DIR="LTR"><HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; CHARSET=iso8859-1">
</HEAD>
<TITLE>lineGatherDigits</TITLE>
<SCRIPT SRC="/library/psdk/linkcss.js"></SCRIPT>
<META NAME="MS-HKWD" CONTENT="lineGatherDigits">
<META NAME="MS-HAID" CONTENT="_tapi2_linegatherdigits">
</HEAD>
<BODY TOPMARGIN="0">
<!--TOOLBAR_START-->
<!--TOOLBAR_EXEMPT-->
<!--TOOLBAR_END-->
<!--SYNC_START-->
<script language="JavaScript" src='/library/synch.js'></script>
<!--SYNC_END-->
<H1><A NAME="_tapi2_linegatherdigits"></A>lineGatherDigits</H1>
<P>The <B>lineGatherDigits</B> function initiates the buffered gathering of digits on the specified call. The application specifies a buffer in which to place the digits and the maximum number of digits to be collected. </P>
<PRE class=syntax><B>LONG WINAPI lineGatherDigits(
HCALL</B><I> hCall</I><B>, </B>
<B> DWORD</B><I> dwDigitModes</I><B>, </B>
<B> LPSTR</B><I> lpsDigits</I><B>, </B>
<B> DWORD</B><I> dwNumDigits</I><B>, </B>
<B> LPCSTR</B><I> lpszTerminationDigits</I><B>, </B>
<B> DWORD</B><I> dwFirstDigitTimeout</I><B>, </B>
<B> DWORD</B><I> dwInterDigitTimeout </I>
<B>);</B></PRE>
<H4>Parameters</H4>
<DL>
<DT><I>hCall</I> </DT>
<DD>A handle to the call on which digits are to be gathered. The application must be an owner of the call. The call state of <I>hCall</I> can be any state. </DD>
<DT><I>dwDigitModes</I> </DT>
<DD>The digit mode(s) to be monitored. This parameter uses one or more of the <A HREF="constnts_56gj.htm" tppabs="http://msdn.microsoft.com/library/psdk/tapi22/constnts_56gj.htm">LINEDIGITMODE_ Constants</A>.</DD>
<DT><I>lpsDigits</I> </DT>
<DD>A pointer to the buffer where detected digits are to be stored as text characters. Digits may not show up in the buffer one at a time as they are collected. Only after a <A HREF="msgs_65mb.htm" tppabs="http://msdn.microsoft.com/library/psdk/tapi22/msgs_65mb.htm">LINE_GATHERDIGITS</A> message is received should the content of the buffer be assumed to be valid. If <I>lpsDigits</I> is NULL, the digit gathering currently in progress on the call is terminated and <I>dwNumDigits</I> is ignored. Otherwise, <I>lpsDigits</I> is assumed to have room for <I>dwNumDigits</I> digits. </DD>
<DT><I>dwNumDigits</I> </DT>
<DD>The number of digits to be collected before a LINE_GATHERDIGITS message is sent to the application. The <I>dwNumDigits</I> parameter is ignored when <I>lpsDigits</I> is NULL. This function fails if <I>dwNumDigits</I> is zero. </DD>
<DT><I>lpszTerminationDigits</I> </DT>
<DD>Specifies a null-terminated string of termination digits as text characters. If one of the digits in the string is detected, that termination digit is appended to the buffer, digit collection is terminated, and the <A HREF="msgs_65mb.htm" tppabs="http://msdn.microsoft.com/library/psdk/tapi22/msgs_65mb.htm">LINE_GATHERDIGITS</A> message is sent to the application.
<P>The list of valid characters is dependent on the constant provided in <I>dwDigitModes</I>. For a list of the valid characters for each possible mode, see <A HREF="constnts_56gj.htm" tppabs="http://msdn.microsoft.com/library/psdk/tapi22/constnts_56gj.htm">LINEDIGITMODE_ Constants</A>.
<P>If this pointer is NULL, or if it points to an empty string, the function behaves as though no termination digits were supplied.
</DD>
<DT><I>dwFirstDigitTimeout</I> </DT>
<DD>The time duration in milliseconds in which the first digit is expected. If the first digit is not received in this timeframe, digit collection is aborted and a <A HREF="msgs_65mb.htm" tppabs="http://msdn.microsoft.com/library/psdk/tapi22/msgs_65mb.htm">LINE_GATHERDIGITS</A> message is sent to the application. The buffer only contains the NULL character, indicating that no digits were received and the first digit timeout terminated digit gathering. The call's line-device capabilities specify the valid range for this parameter or indicate that timeouts are not supported. </DD>
<DT><I>dwInterDigitTimeout</I> </DT>
<DD>The maximum time duration in milliseconds between consecutive digits. If no digit is received in this timeframe, digit collection is aborted and a LINE_GATHERDIGITS message is sent to the application. The buffer only contains the digits collected up to this point followed by a NULL character, indicating that an interdigit timeout terminated digit gathering. The call's line-device capabilities specify the valid range for this parameter or indicate that timeouts are not supported.
</DD>
</DL>
<H4>Return Values</H4>
<P>Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are: </P>
<P>LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALCALLSTATE, LINEERR_NOTOWNER, LINEERR_INVALDIGITMODE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITS, LINEERR_OPERATIONFAILED, LINEERR_INVALPARAM, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED.</P>
<H4>Remarks</H4>
<P>Digit collection is terminated when the requested number of digits has been collected. It is also terminated when one of the digits detected matches a digit in <I>szTerminationDigits</I> before the specified number of digits has been collected. The detected termination digit is also placed in the buffer and the partial buffer is returned. </P>
<P>Another way of canceling digit collection occurs when one of the timeouts expires. The <I>dwFirstDigitTimeout</I> expires if the first digit is not received in this time period. The <I>dwInterDigitTimout</I> expires if the second, third, (and so forth) digit is not received within that time period from the previously detected digit, and a partial buffer is returned. </P>
<P>A fourth method for terminating digit collection is by calling this function again while collection is in progress. The old collection session is terminated, any digits collected up to that point are copied to the buffer supplied from the previous call to this function, and the buffer is delivered when the <A HREF="msgs_65mb.htm" tppabs="http://msdn.microsoft.com/library/psdk/tapi22/msgs_65mb.htm">LINE_GATHERDIGITS</A> message is sent to the application. The mechanism for terminating digit gathering without initiating another gathering of the digits is to invoke this function with <I>lpsDigits</I> equal to NULL. </P>
<P>This function is considered successful if digit collection has been correctly initiated, not if digit collection has terminated. In all cases where a partial buffer is returned, valid digits (if any) are followed by a NULL character. </P>
<P>Although this function can be invoked in any call state, digits can typically only be gathered while the call is in the <I>connected</I> state. </P>
<P>The message LINE_GATHERDIGITS is sent only to the application that initiated the request. It is also sent when partial buffers are returned because of timeouts or matching termination digits, or when the request is canceled by another <B>lineGatherDigits</B> request on the call. Only one gather-digits request can be active on a call at any given time across all applications that are owners of the call. Given the asynchronous behavior of the operation, an application that issues multiple <B>lineGatherDigits</B> requests in quick succession may be able to do so and receive several LINE_GATHERDIGITS messages later. While this would be unusual application behavior, the application is able to count the number of these messages to allow cancel messages to be matched with the earlier requests. In any case, only the most recent request should be assumed to be valid. </P>
<P class=note><B>Note</B> When an application invokes any asynchronous operation that writes data back into application memory, the application must keep that memory available for writing until a <A HREF="msgs_65mh.htm" tppabs="http://msdn.microsoft.com/library/psdk/tapi22/msgs_65mh.htm">LINE_REPLY</A> or <A HREF="msgs_65mb.htm" tppabs="http://msdn.microsoft.com/library/psdk/tapi22/msgs_65mb.htm">LINE_GATHERDIGITS</A> message is received.</P>
<P>An application can use <A HREF="func2_0e43.htm" tppabs="http://msdn.microsoft.com/library/psdk/tapi22/func2_0e43.htm"><B>lineMonitorDigits</B></A> to enable or disable unbuffered digit detection. Each time a digit is detected in this fashion, a <A HREF="msgs_5p0z.htm" tppabs="http://msdn.microsoft.com/library/psdk/tapi22/msgs_5p0z.htm">LINE_MONITORDIGITS</A> message is sent to the application. Both buffered and unbuffered digit detection can be simutaneously enabled for the same call. </P>
<P>Gathering of digits on a conference call applies only to the <I>hConfCall</I>, not to the individual participating calls. </P>
<P>If the <B>lineGatherDigits</B> function is used to cancel a previous request to gather digits, the function copies any digits collected up to that point to the buffer specified in the original function call. The function then sends a LINE_GATHERDIGITS message to the application, regardless of whether the <I>lpszDigits</I> parameter in the second call specifies a NULL or different address. </P>
<H4><A HREF="javascript:if(confirm('http://msdn.microsoft.com/library/psdk/sdkintro/guide_927n.htm \n\n這個(gè)文件不能通過(guò) Teleport Pro 取回, 因?yàn)?地址在一個(gè)域或?yàn)樗拈_(kāi)始地址設(shè)定的邊界的外部路徑上. \n\n你想從服務(wù)器打開(kāi)它嗎?'))window.location='http://msdn.microsoft.com/library/psdk/sdkintro/guide_927n.htm'" tppabs="http://msdn.microsoft.com/library/psdk/sdkintro/guide_927n.htm">Requirements</A> </H4>
<P><B> Windows NT/2000: </B>Requires Windows NT 4.0 SP3 or later.<BR>
<B> Windows 95/98: </B>Requires Windows 95 or later.<BR>
<B> Version: </B>Requires TAPI 1.3 or later.<BR>
<B> Header: </B>Declared in Tapi.h.<BR>
<B> Library: </B>Use Tapi32.lib.<BR>
<B> Unicode: </B>Implemented as Unicode and ANSI versions on all platforms.</P>
<H4>See Also</H4>
<P><A HREF="quickref_1okl.htm" tppabs="http://msdn.microsoft.com/library/psdk/tapi22/quickref_1okl.htm">TAPI 2.2 Reference Overview</A>, <A HREF="quickref_6gvn.htm" tppabs="http://msdn.microsoft.com/library/psdk/tapi22/quickref_6gvn.htm">Supplementary Line Service Functions</A>, <A HREF="msgs_65mb.htm" tppabs="http://msdn.microsoft.com/library/psdk/tapi22/msgs_65mb.htm">LINE_GATHERDIGITS</A>, <A HREF="msgs_65mh.htm" tppabs="http://msdn.microsoft.com/library/psdk/tapi22/msgs_65mh.htm">LINE_REPLY</A>, <A HREF="msgs_5p0z.htm" tppabs="http://msdn.microsoft.com/library/psdk/tapi22/msgs_5p0z.htm">LINE_MONITORDIGITS</A>, <A HREF="func2_0e43.htm" tppabs="http://msdn.microsoft.com/library/psdk/tapi22/func2_0e43.htm"><B>lineMonitorDigits</B></A></P>
<DIV CLASS="footer">Built on Monday, August 14, 2000</DIV>
<!--FOOTER_START-->
<DIV CLASS="footer" STYLE="color:#000000;font-size:90%;">
<A HREF="mailto:sdkfdbk@microsoft.com">Send feedback</A> to the Platform SDK.</P>
<P><A HREF="javascript:if(confirm('http://msdn.microsoft.com/isapi/gomscom.asp?TARGET=/info/cpyright.htm \n\n這個(gè)文件不能通過(guò) Teleport Pro 取回, 因?yàn)?地址在一個(gè)域或?yàn)樗拈_(kāi)始地址設(shè)定的邊界的外部路徑上. \n\n你想從服務(wù)器打開(kāi)它嗎?'))window.location='http://msdn.microsoft.com/isapi/gomscom.asp?TARGET=/info/cpyright.htm'" tppabs="http://msdn.microsoft.com/isapi/gomscom.asp?TARGET=/info/cpyright.htm" TARGET="_top">© 1999 Microsoft Corporation. All rights reserved. Terms of use.</A></P>
</DIV>
<!--FOOTER_END-->
</BODY>
</HTML>
?? 快捷鍵說(shuō)明
復(fù)制代碼
Ctrl + C
搜索代碼
Ctrl + F
全屏模式
F11
切換主題
Ctrl + Shift + D
顯示快捷鍵
?
增大字號(hào)
Ctrl + =
減小字號(hào)
Ctrl + -