MessageQueue.BeginPeek 方法

定義

啟始非同步窺視作業,方法是告知訊息佇列開始窺視訊息,並在完成時告知事件處理常式。Initiates an asynchronous peek operation by telling Message Queuing to begin peeking a message and notify the event handler when finished.

多載

BeginPeek(TimeSpan, Object, AsyncCallback)

啟始有指定逾時和指定狀態物件的非同步窺視作業,會在作業的整個存留期內提供相關的資訊。Initiates an asynchronous peek operation that has a specified time-out and a specified state object, which provides associated information throughout the operation's lifetime. 這個多載會透過回呼,接收作業的事件處理常式的識別通知。This overload receives notification, through a callback, of the identity of the event handler for the operation. 在訊息可以於佇列中使用或發生逾時之後,作業才會完成。The operation is not complete until either a message becomes available in the queue or the time-out occurs.

BeginPeek(TimeSpan, Object)

啟始有指定逾時和指定狀態物件的非同步窺視作業,會在作業的整個存留期內提供相關的資訊。Initiates an asynchronous peek operation that has a specified time-out and a specified state object, which provides associated information throughout the operation's lifetime. 在訊息可以於佇列中使用或發生逾時之後,作業才會完成。The operation is not complete until either a message becomes available in the queue or the time-out occurs.

BeginPeek(TimeSpan, Cursor, PeekAction, Object, AsyncCallback)

啟始非同步窺視作業,該作業具有指定的逾時,並使用指定的游標、指定的窺視動作和指定的狀態物件。Initiates an asynchronous peek operation that has a specified time-out and that uses a specified cursor, a specified peek action, and a specified state object. 狀態物件提供整個作業存留期的相關聯資訊。The state object provides associated information throughout the lifetime of the operation. 這個多載會透過回呼,接收作業的事件處理常式的識別通知。This overload receives notification, through a callback, of the identity of the event handler for the operation. 在訊息可以於佇列中使用或發生逾時之後,作業才會完成。The operation is not complete until either a message becomes available in the queue or the time-out occurs.

BeginPeek()

啟始沒有逾時的非同步窺視作業。作業要等到訊息可以在佇列中使用之後才算完成。Initiates an asynchronous peek operation that has no time-out. The operation is not complete until a message becomes available in the queue.

BeginPeek(TimeSpan)

啟始有指定逾時的非同步窺視作業。在訊息可以於佇列中使用或發生逾時之後,作業才會完成。Initiates an asynchronous peek operation that has a specified time-out. The operation is not complete until either a message becomes available in the queue or the time-out occurs.

BeginPeek(TimeSpan, Object, AsyncCallback)

啟始有指定逾時和指定狀態物件的非同步窺視作業,會在作業的整個存留期內提供相關的資訊。Initiates an asynchronous peek operation that has a specified time-out and a specified state object, which provides associated information throughout the operation's lifetime. 這個多載會透過回呼,接收作業的事件處理常式的識別通知。This overload receives notification, through a callback, of the identity of the event handler for the operation. 在訊息可以於佇列中使用或發生逾時之後,作業才會完成。The operation is not complete until either a message becomes available in the queue or the time-out occurs.

public:
 IAsyncResult ^ BeginPeek(TimeSpan timeout, System::Object ^ stateObject, AsyncCallback ^ callback);
public IAsyncResult BeginPeek (TimeSpan timeout, object stateObject, AsyncCallback callback);
member this.BeginPeek : TimeSpan * obj * AsyncCallback -> IAsyncResult
Public Function BeginPeek (timeout As TimeSpan, stateObject As Object, callback As AsyncCallback) As IAsyncResult

參數

timeout
TimeSpan

TimeSpan,指出等待訊息變成可以使用的時間間隔。A TimeSpan that indicates the interval of time to wait for a message to become available.

stateObject
Object

應用程式指定的狀態物件,包含與非同步作業相關的資訊。A state object, specified by the application, that contains information associated with the asynchronous operation.

callback
AsyncCallback

會接收非同步作業完成通知的 AsyncCallbackThe AsyncCallback that will receive the notification of the asynchronous operation completion.

傳回

識別傳送的非同步要求的 IAsyncResultThe IAsyncResult that identifies the posted asynchronous request.

例外狀況

指定給 timeout 參數的值無效。The value specified for the timeout parameter is not valid.

存取訊息佇列方法時發生錯誤。An error occurred when accessing a Message Queuing method.

範例

下列程式碼範例會建立非同步查看作業。The following code example creates an asynchronous peek operation. 程式碼範例會將訊息傳送至本機訊息佇列,然後呼叫 BeginPeek(TimeSpan, Object, AsyncCallback),傳入:10秒的超時值;識別該特定訊息的唯一整數;AsyncCallback 的新實例,可識別事件處理常式,MyPeekCompletedThe code example sends a message to a local message queue, then calls BeginPeek(TimeSpan, Object, AsyncCallback), passing in: a time-out value of ten seconds; a unique integer that identifies that particular message; and a new instance of AsyncCallback that identifies the event handler, MyPeekCompleted. 當引發 PeekCompleted 事件時,事件處理常式會查看訊息,並將訊息內文和整數訊息識別碼寫入畫面。When a PeekCompleted event is raised, the event handler peeks at the message and writes the message body and the integer message identifier to the screen.

#using <System.Messaging.dll>
#using <System.dll>

using namespace System;
using namespace System::Messaging;

// Creates a new queue.
void CreateQueue(String^ queuePath, bool transactional)
{
    if(!MessageQueue::Exists(queuePath))
    {
        MessageQueue^ queue = MessageQueue::Create(queuePath, transactional);
        queue->Close();      
    }
    else
    {
        Console::WriteLine("{0} already exists.", queuePath);
    }
}

// Provides an event handler for the PeekCompleted event.
void MyPeekCompleted(IAsyncResult^ asyncResult)
{
    // Connect to the queue.
    MessageQueue^ queue = gcnew MessageQueue(".\\exampleQueue");

    // End the asynchronous peek operation.
    Message^ msg = queue->EndPeek(asyncResult);

    // Display the message information on the screen.
    Console::WriteLine("Message number: {0}", asyncResult->AsyncState);
    Console::WriteLine("Message body: {0}", msg->Body);

    // Receive the message. This will remove the message from the queue.
    msg = queue->Receive(TimeSpan::FromSeconds(10.0));

    queue->Close();
}

int main()
{
    // Represents a state object associated with each message.
    int messageNumber = 0;

    // Create a non-transactional queue on the local computer.
    // Note that the queue might not be immediately accessible, and
    // therefore this example might throw an exception of type
    // System.Messaging.MessageQueueException when trying to send a
    // message to the newly created queue.
    CreateQueue(".\\exampleQueue", false);

    // Connect to a queue on the local computer.
    MessageQueue^ queue = gcnew MessageQueue(".\\exampleQueue");

    // Send a message to the queue.
    queue->Send("Example Message");

    // Begin the asynchronous peek operation.
    queue->BeginPeek(TimeSpan::FromSeconds(10.0), messageNumber++,
        gcnew AsyncCallback(MyPeekCompleted));

    // Simulate doing other work on the current thread.
    System::Threading::Thread::Sleep(TimeSpan::FromSeconds(10.0));

    queue->Close();
}


using System;
using System.Messaging;

public class QueueExample
{
    // Represents a state object associated with each message.
    static int messageNumber = 0;

    public static void Main()
    {
        // Create a non-transactional queue on the local computer.
        // Note that the queue might not be immediately accessible, and
        // therefore this example might throw an exception of type
        // System.Messaging.MessageQueueException when trying to send a
        // message to the newly created queue.
        CreateQueue(".\\exampleQueue", false);

        // Connect to a queue on the local computer.
        MessageQueue queue = new MessageQueue(".\\exampleQueue");

        // Send a message to the queue.
        queue.Send("Example Message");

        // Begin the asynchronous peek operation.
        queue.BeginPeek(TimeSpan.FromSeconds(10.0), messageNumber++,
            new AsyncCallback(MyPeekCompleted));

        // Simulate doing other work on the current thread.
        System.Threading.Thread.Sleep(TimeSpan.FromSeconds(10.0));

        return;
    }

    // Creates a new queue.
    public static void CreateQueue(string queuePath, bool transactional)
    {
        if(!MessageQueue.Exists(queuePath))
        {
            MessageQueue.Create(queuePath, transactional);
        }
        else
        {
            Console.WriteLine(queuePath + " already exists.");
        }
    }

    // Provides an event handler for the PeekCompleted event.
    private static void MyPeekCompleted(IAsyncResult asyncResult)
    {
        // Connect to the queue.
        MessageQueue queue = new MessageQueue(".\\exampleQueue");

        // End the asynchronous peek operation.
        Message msg = queue.EndPeek(asyncResult);

        // Display the message information on the screen.
        Console.WriteLine("Message number: {0}", (int)asyncResult.AsyncState);
        Console.WriteLine("Message body: {0}", (string)msg.Body);

        // Receive the message. This will remove the message from the queue.
        msg = queue.Receive(TimeSpan.FromSeconds(10.0));
    }
}

備註

當您使用這個多載時,當佇列中有訊息可供使用時,或當指定的時間間隔已過期時,就會直接叫用回呼參數中指定的回呼;不會引發 PeekCompleted 事件。When you use this overload, the callback specified in the callback parameter is invoked directly when a message becomes available in the queue or when the specified interval of time has expired; the PeekCompleted event is not raised. BeginPeek 的其他多載依賴此元件來引發 PeekCompleted 事件。The other overloads of BeginPeek rely on this component to raise the PeekCompleted event.

如果訊息已經存在於佇列中,也會引發 PeekCompletedPeekCompleted is also raised if a message already exists in the queue.

BeginPeek 方法會立即傳回,但是在呼叫事件處理常式之前,非同步作業不會完成。The BeginPeek method returns immediately, but the asynchronous operation is not completed until the event handler is called.

因為 BeginPeek 是非同步,所以您可以呼叫它來查看佇列,而不會封鎖目前執行的執行緒。Because BeginPeek is asynchronous, you can call it to peek the queue without blocking the current thread of execution. 若要同步查看佇列,請使用 Peek 方法。To synchronously peek the queue, use the Peek method.

非同步作業完成後,您可以在事件處理常式中再次呼叫 BeginPeekBeginReceive,以繼續接收通知。Once an asynchronous operation completes, you can call BeginPeek or BeginReceive again in the event handler to keep receiving notifications.

BeginPeek 會傳回 IAsyncResult,以識別方法啟動的非同步作業。BeginPeek returns a IAsyncResult that identifies the asynchronous operation that the method started. 雖然您通常不會在呼叫 EndPeek(IAsyncResult) 之前使用此 IAsyncResult,但您可以在作業的整個存留期間使用此。You can use this IAsyncResult throughout the lifetime of the operation, although you generally do not use it until EndPeek(IAsyncResult) is called. 不過,如果您啟動數個非同步作業,您可以將其 IAsyncResult 值放在陣列中,並指定是否要等候所有作業或任何作業完成。However, if you start several asynchronous operations, you can place their IAsyncResult values in an array and specify whether to wait for all operations or any operation to complete. 在此情況下,您可以使用 IAsyncResultAsyncWaitHandle 屬性來識別已完成的作業。In this case, you use the AsyncWaitHandle property of the IAsyncResult to identify the completed operation.

狀態物件會將狀態資訊與作業相關聯。The state object associates state information with the operation. 例如,如果您多次呼叫 BeginPeek 來起始多個作業,您可以透過您所定義的個別狀態物件,來識別每個操作。For example, if you call BeginPeek multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define.

下表顯示這個方法是否可在各種工作組模式中使用。The following table shows whether this method is available in various Workgroup modes.

工作組模式Workgroup mode 可用Available
本機電腦Local computer Yes
本機電腦和直接格式名稱Local computer and direct format name Yes
遠端電腦Remote computer No
遠端電腦和直接格式名稱Remote computer and direct format name Yes

執行緒安全性

方法不是安全線程。The method is not thread safe.

另請參閱

BeginPeek(TimeSpan, Object)

啟始有指定逾時和指定狀態物件的非同步窺視作業,會在作業的整個存留期內提供相關的資訊。Initiates an asynchronous peek operation that has a specified time-out and a specified state object, which provides associated information throughout the operation's lifetime. 在訊息可以於佇列中使用或發生逾時之後,作業才會完成。The operation is not complete until either a message becomes available in the queue or the time-out occurs.

public:
 IAsyncResult ^ BeginPeek(TimeSpan timeout, System::Object ^ stateObject);
public IAsyncResult BeginPeek (TimeSpan timeout, object stateObject);
member this.BeginPeek : TimeSpan * obj -> IAsyncResult
Public Function BeginPeek (timeout As TimeSpan, stateObject As Object) As IAsyncResult

參數

timeout
TimeSpan

TimeSpan,指出等待訊息變成可以使用的時間間隔。A TimeSpan that indicates the interval of time to wait for a message to become available.

stateObject
Object

應用程式指定的狀態物件,包含與非同步作業相關的資訊。A state object, specified by the application, that contains information associated with the asynchronous operation.

傳回

識別傳送的非同步要求的 IAsyncResultThe IAsyncResult that identifies the posted asynchronous request.

例外狀況

指定給 timeout 參數的值無效。The value specified for the timeout parameter is not valid.

存取訊息佇列方法時發生錯誤。An error occurred when accessing a Message Queuing method.

範例

下列程式碼範例會使用佇列路徑 ".\myQueue" 來建立非同步查看作業。The following code example creates an asynchronous peek operation, using the queue path ".\myQueue". 它會建立事件處理常式 MyPeekCompleted,並將它附加至 PeekCompleted 事件處理常式委派。It creates an event handler, MyPeekCompleted, and attaches it to the PeekCompleted event handler delegate. 呼叫 BeginPeek,並以一分鐘的時間執行。BeginPeek is called, with a time-out of one minute. BeginPeek 的每個呼叫都有唯一的相關聯整數,可識別該特定作業。Each call to BeginPeek has a unique associated integer that identifies that particular operation. 當引發 PeekCompleted 事件或超時時間過期時,會抓取訊息(如果有的話),並將其主體和作業特定的整數識別碼寫入螢幕。When a PeekCompleted event is raised or the time-out expired, the message, if one exists, is retrieved and its body and the operation-specific integer identifier are written to the screen. 然後再次呼叫 BeginPeek,以使用與剛完成之作業相同的超時時間和相關聯的整數來起始新的非同步查看作業。Then BeginPeek is called again to initiate a new asynchronous peek operation with the same time-out and the associated integer of the just completed operation.

#using <system.dll>
#using <system.messaging.dll>

using namespace System;
using namespace System::Messaging;
ref class MyNewQueue
{
public:

   // Represents a state object associated with each message.
   static int messageNumber = 0;

   // Provides an event handler for the PeekCompleted
   // event.
   //
   static void MyPeekCompleted( Object^ source, PeekCompletedEventArgs^ asyncResult )
   {
      try
      {
         // Connect to the queue.
         MessageQueue^ mq = dynamic_cast<MessageQueue^>(source);

         // End the asynchronous peek operation.
         Message^ m = mq->EndPeek( asyncResult->AsyncResult );

         // Display message information on the screen, 
         // including the message number (state object).
         Console::WriteLine( "Message: {0} {1}", asyncResult->AsyncResult->AsyncState, static_cast<String^>(m->Body) );

         // Restart the asynchronous peek operation, with the 
         // same time-out.
         mq->BeginPeek( TimeSpan(0,1,0), messageNumber++ );
      }
      catch ( MessageQueueException^ e ) 
      {
         if ( e->MessageQueueErrorCode == MessageQueueErrorCode::IOTimeout )
         {
            Console::WriteLine( e );
         }

         // Handle other sources of MessageQueueException.
      }

      // Handle other exceptions.
      return;
   }
};


// Provides an entry point into the application.
//         
// This example performs asynchronous peek operation
// processing.
int main()
{
   // Create an instance of MessageQueue. Set its formatter.
   MessageQueue^ myQueue = gcnew MessageQueue( ".\\myQueue" );
   array<Type^>^p = gcnew array<Type^>(1);
   p[ 0 ] = String::typeid;
   myQueue->Formatter = gcnew XmlMessageFormatter( p );

   // Add an event handler for the PeekCompleted event.
   myQueue->PeekCompleted += gcnew PeekCompletedEventHandler( MyNewQueue::MyPeekCompleted );

   // Begin the asynchronous peek operation with a timeout 
   // of one minute.
   myQueue->BeginPeek( TimeSpan(0,1,0), MyNewQueue::messageNumber++ );

   // Do other work on the current thread.
   return 0;
}
using System;
using System.Messaging;

namespace MyProject
{
    /// <summary>
    /// Provides a container class for the example.
    /// </summary>
    public class MyNewQueue
    {
        // Represents a state object associated with each message.
        static int messageNumber = 0;

        //**************************************************
        // Provides an entry point into the application.
        //		 
        // This example performs asynchronous peek operation
        // processing.
        //**************************************************

        public static void Main()
        {
            // Create an instance of MessageQueue. Set its formatter.
            MessageQueue myQueue = new MessageQueue(".\\myQueue");
            myQueue.Formatter = new XmlMessageFormatter(new Type[]
                {typeof(String)});

            // Add an event handler for the PeekCompleted event.
            myQueue.PeekCompleted += new 
                PeekCompletedEventHandler(MyPeekCompleted);
            
            // Begin the asynchronous peek operation with a time-out 
            // of one minute.
            myQueue.BeginPeek(new TimeSpan(0,1,0), messageNumber++);
            
            // Do other work on the current thread.

            return;
        }


        //**************************************************
        // Provides an event handler for the PeekCompleted
        // event.
        //**************************************************
        
        private static void MyPeekCompleted(Object source, 
            PeekCompletedEventArgs asyncResult)
        {
            try
            {
                // Connect to the queue.
                MessageQueue mq = (MessageQueue)source;

                // End the asynchronous peek operation.
                Message m = mq.EndPeek(asyncResult.AsyncResult);

                // Display message information on the screen, 
                // including the message number (state object).
                Console.WriteLine("Message: " + 
                    (int)asyncResult.AsyncResult.AsyncState + " " 
                    +(string)m.Body);

                // Restart the asynchronous peek operation, with the 
                // same time-out.
                mq.BeginPeek(new TimeSpan(0,1,0), messageNumber++);

            }

            catch(MessageQueueException e)
            {
                if (e.MessageQueueErrorCode == 
                    MessageQueueErrorCode.IOTimeout)
                {
                    Console.WriteLine(e.ToString());
                }

                // Handle other sources of MessageQueueException.
            }
            
            // Handle other exceptions.
            
            return; 
        }
    }
}
Imports System.Messaging


   
' Provides a container class for the example.

Public Class MyNewQueue

        ' Represents a state object associated with each message.
        Private Shared messageNumber As Integer = 0



        ' Provides an entry point into the application.
        '		 
        ' This example performs asynchronous peek operation
        ' processing.


        Public Shared Sub Main()
            ' Create an instance of MessageQueue. Set its formatter.
            Dim myQueue As New MessageQueue(".\myQueue")
            myQueue.Formatter = New XmlMessageFormatter(New Type() _
                {GetType([String])})

            ' Add an event handler for the PeekCompleted event.
            AddHandler myQueue.PeekCompleted, AddressOf _
                MyPeekCompleted

            ' Begin the asynchronous peek operation with a time-out 
            ' of one minute.
            myQueue.BeginPeek(New TimeSpan(0, 1, 0), messageNumber)
            messageNumber += 1

            ' Do other work on the current thread.
            Return
        End Sub



        ' Provides an event handler for the PeekCompleted
        ' event.


        Private Shared Sub MyPeekCompleted(ByVal [source] As _
            [Object], ByVal asyncResult As _
            PeekCompletedEventArgs)

            Try
                ' Connect to the queue.
                Dim mq As MessageQueue = _
                    CType([source], MessageQueue)

                ' End the asynchronous peek operation.
                Dim m As Message = _
                    mq.EndPeek(asyncResult.AsyncResult)

                ' Display message information on the screen, 
                ' including(the) message number (state object).
                Console.WriteLine(("Message: " + _
                    CInt(asyncResult.AsyncResult.AsyncState) + _
                    " " + CStr(m.Body)))

                ' Restart the asynchronous peek operation, with the 
                ' same time-out.
                mq.BeginPeek(New TimeSpan(0, 1, 0), messageNumber)
                messageNumber += 1


            Catch e As MessageQueueException

                If e.MessageQueueErrorCode = _
                    MessageQueueErrorCode.IOTimeout Then

                    Console.WriteLine(e.ToString())

                    ' Handle other sources of MessageQueueException.

                End If

                ' Handle other exceptions.

            End Try

            Return

        End Sub

End Class

備註

在非同步處理中,您可以使用 BeginPeek 在佇列中有訊息可供使用時,或指定的時間間隔已過期時,引發 PeekCompleted 事件。In asynchronous processing, you use BeginPeek to raise the PeekCompleted event when a message becomes available in the queue or when the specified interval of time has expired.

如果訊息已經存在於佇列中,也會引發 PeekCompletedPeekCompleted is also raised if a message already exists in the queue.

使用此多載,將資訊與將在作業存留期內保留的作業產生關聯。Use this overload to associate information with the operation that will be preserved throughout the operation's lifetime. 事件處理常式可以藉由查看與作業相關聯 IAsyncResultAsyncState 屬性來存取這項資訊。The event handler can access this information by looking at the AsyncState property of the IAsyncResult that is associated with the operation.

若要使用 BeginPeek,請建立一個事件處理常式來處理非同步作業的結果,並將它與您的事件委派產生關聯。To use BeginPeek, create an event handler that processes the results of the asynchronous operation, and associate it with your event delegate. BeginPeek 會起始非同步查看作業;當訊息抵達佇列時,會透過引發 PeekCompleted 事件來通知 MessageQueueBeginPeek initiates an asynchronous peek operation; the MessageQueue is notified, through the raising of the PeekCompleted event, when a message arrives in the queue. 然後 MessageQueue 可以藉由呼叫 EndPeek(IAsyncResult) 或藉由使用 PeekCompletedEventArgs來抓取結果,來存取訊息。The MessageQueue can then access the message by calling EndPeek(IAsyncResult) or by retrieving the result using the PeekCompletedEventArgs.

BeginPeek 方法會立即傳回,但是在呼叫事件處理常式之前,非同步作業不會完成。The BeginPeek method returns immediately, but the asynchronous operation is not completed until the event handler is called.

因為 BeginPeek 是非同步,所以您可以呼叫它來查看佇列,而不會封鎖目前執行的執行緒。Because BeginPeek is asynchronous, you can call it to peek the queue without blocking the current thread of execution. 若要同步查看佇列,請使用 Peek 方法。To synchronously peek the queue, use the Peek method.

非同步作業完成後,您可以在事件處理常式中再次呼叫 BeginPeekBeginReceive,以繼續接收通知。Once an asynchronous operation completes, you can call BeginPeek or BeginReceive again in the event handler to keep receiving notifications.

BeginPeek 會傳回 IAsyncResult,以識別方法啟動的非同步作業。BeginPeek returns a IAsyncResult that identifies the asynchronous operation that the method started. 雖然您通常不會在呼叫 EndPeek(IAsyncResult) 之前使用此 IAsyncResult,但您可以在作業的整個存留期間使用此。You can use this IAsyncResult throughout the lifetime of the operation, although you generally do not use it until EndPeek(IAsyncResult) is called. 不過,如果您啟動數個非同步作業,您可以將其 IAsyncResult 值放在陣列中,並指定是否要等候所有作業或任何作業完成。However, if you start several asynchronous operations, you can place their IAsyncResult values in an array and specify whether to wait for all operations or any operation to complete. 在此情況下,您可以使用 IAsyncResultAsyncWaitHandle 屬性來識別已完成的作業。In this case, you use the AsyncWaitHandle property of the IAsyncResult to identify the completed operation.

這個多載會指定超時和狀態物件。This overload specifies a time-out and a state object. 如果 timeout 參數所指定的間隔過期,這個元件就會引發 PeekCompleted 事件。If the interval specified by the timeout parameter expires, this component raises the PeekCompleted event. 因為不存在任何訊息,後續對 EndPeek(IAsyncResult) 的呼叫將會擲回例外狀況。Because no message exists, a subsequent call to EndPeek(IAsyncResult) will throw an exception.

狀態物件會將狀態資訊與作業相關聯。The state object associates state information with the operation. 例如,如果您多次呼叫 BeginPeek 來起始多個作業,您可以透過您所定義的個別狀態物件,來識別每個操作。For example, if you call BeginPeek multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define. 如需此案例的圖例,請參閱範例一節。For an illustration of this scenario, see the Example section.

您也可以使用狀態物件在進程執行緒之間傳遞資訊。You can also use the state object to pass information across process threads. 如果執行緒已啟動,但回呼是在非同步案例中的不同執行緒上,則會封送處理狀態物件,並連同事件中的資訊一起回傳。If a thread is started but the callback is on a different thread in an asynchronous scenario, the state object is marshaled and passed back along with information from the event.

如果 falseCanRead,就會引發完成事件,但在呼叫 EndPeek(IAsyncResult)時,將會擲回例外狀況(exception)。If CanRead is false, the completion event is raised, but an exception will be thrown when calling EndPeek(IAsyncResult).

下表顯示這個方法是否可在各種工作組模式中使用。The following table shows whether this method is available in various Workgroup modes.

工作組模式Workgroup mode 可用Available
本機電腦Local computer Yes
本機電腦和直接格式名稱Local computer and direct format name Yes
遠端電腦Remote computer No
遠端電腦和直接格式名稱Remote computer and direct format name Yes

執行緒安全性

方法不是安全線程。The method is not thread safe.

另請參閱

BeginPeek(TimeSpan, Cursor, PeekAction, Object, AsyncCallback)

啟始非同步窺視作業,該作業具有指定的逾時,並使用指定的游標、指定的窺視動作和指定的狀態物件。Initiates an asynchronous peek operation that has a specified time-out and that uses a specified cursor, a specified peek action, and a specified state object. 狀態物件提供整個作業存留期的相關聯資訊。The state object provides associated information throughout the lifetime of the operation. 這個多載會透過回呼,接收作業的事件處理常式的識別通知。This overload receives notification, through a callback, of the identity of the event handler for the operation. 在訊息可以於佇列中使用或發生逾時之後,作業才會完成。The operation is not complete until either a message becomes available in the queue or the time-out occurs.

public:
 IAsyncResult ^ BeginPeek(TimeSpan timeout, System::Messaging::Cursor ^ cursor, System::Messaging::PeekAction action, System::Object ^ state, AsyncCallback ^ callback);
public IAsyncResult BeginPeek (TimeSpan timeout, System.Messaging.Cursor cursor, System.Messaging.PeekAction action, object state, AsyncCallback callback);
member this.BeginPeek : TimeSpan * System.Messaging.Cursor * System.Messaging.PeekAction * obj * AsyncCallback -> IAsyncResult

參數

timeout
TimeSpan

TimeSpan,指出等待訊息變成可以使用的時間間隔。A TimeSpan that indicates the interval of time to wait for a message to become available.

cursor
Cursor

Cursor,保留訊息佇列中的特定位置。A Cursor that maintains a specific position in the message queue.

action
PeekAction

其中一個 PeekAction 值。One of the PeekAction values. 指出要窺視佇列中的目前訊息,還是下一則訊息。Indicates whether to peek at the current message in the queue, or the next message.

state
Object

應用程式指定的狀態物件,包含與非同步作業相關的資訊。A state object, specified by the application, that contains information associated with the asynchronous operation.

callback
AsyncCallback

AsyncCallback,接收非同步作業的完成通知。The AsyncCallback that receives the notification of the asynchronous operation completion.

傳回

識別傳送的非同步要求的 IAsyncResultThe IAsyncResult that identifies the posted asynchronous request.

例外狀況

action 參數指定 PeekAction.CurrentPeekAction.Next 以外的值。A value other than PeekAction.Current or PeekAction.Next was specified for the action parameter.

cursor 參數為 nullThe cursor parameter is null.

指定給 timeout 參數的值無效。The value specified for the timeout parameter is not valid.

存取訊息佇列方法時發生錯誤。An error occurred when accessing a Message Queuing method.

備註

當您使用這個多載時,當佇列中的訊息可供使用時,或指定的時間間隔已過期時,就會直接叫用回呼參數中指定的回呼。When you use this overload, the callback specified in the callback parameter is invoked directly when a message becomes available in the queue or when the specified interval of time has expired. 不會引發 PeekCompleted 事件。The PeekCompleted event is not raised. BeginPeek 的其他多載依賴此元件來引發 PeekCompleted 事件。The other overloads of BeginPeek rely on this component to raise the PeekCompleted event.

如果訊息已經存在於佇列中,也會引發 PeekCompletedPeekCompleted is also raised if a message already exists in the queue.

BeginPeek 方法會立即傳回,但是在呼叫事件處理常式之前,非同步作業不會完成。The BeginPeek method returns immediately, but the asynchronous operation is not completed until the event handler is called.

因為 BeginPeek 是非同步,所以您可以呼叫它來查看佇列,而不會封鎖目前執行的執行緒。Because BeginPeek is asynchronous, you can call it to peek the queue without blocking the current thread of execution. 若要同步查看佇列,請使用 Peek 方法。To synchronously peek the queue, use the Peek method.

非同步作業完成後,您可以在事件處理常式中再次呼叫 BeginPeekBeginReceive,以繼續接收通知。Once an asynchronous operation completes, you can call BeginPeek or BeginReceive again in the event handler to keep receiving notifications.

BeginPeek 會傳回識別方法所啟動之非同步作業的 IAsyncResultBeginPeek returns a IAsyncResult that identifies the asynchronous operation started by the method. 雖然您通常不會在呼叫 EndPeek(IAsyncResult) 之前使用此 IAsyncResult,但您可以在作業的整個存留期間使用此。You can use this IAsyncResult throughout the lifetime of the operation, although you generally do not use it until EndPeek(IAsyncResult) is called. 不過,如果您啟動數個非同步作業,您可以將其 IAsyncResult 值放在陣列中,並指定是否要等候所有作業或任何作業完成。However, if you start several asynchronous operations, you can place their IAsyncResult values in an array and specify whether to wait for all operations or any operation to complete. 在此情況下,請使用 IAsyncResultAsyncWaitHandle 屬性來識別已完成的作業。In this case, use the AsyncWaitHandle property of the IAsyncResult to identify the completed operation.

狀態物件會將狀態資訊與作業相關聯。The state object associates state information with the operation. 例如,如果您多次呼叫 BeginPeek 來起始多個作業,您可以透過您所定義的個別狀態物件,來識別每個操作。For example, if you call BeginPeek multiple times to initiate multiple operations, you can identify each operation through a separate state object that you define.

下表顯示這個方法是否可在各種工作組模式中使用。The following table shows whether this method is available in various Workgroup modes.

工作組模式Workgroup mode 可用Available
本機電腦Local computer Yes
本機電腦和直接格式名稱Local computer and direct format name Yes
遠端電腦Remote computer No
遠端電腦和直接格式名稱Remote computer and direct format name Yes

執行緒安全性

方法不是安全線程。The method is not thread safe.

另請參閱

BeginPeek()

啟始沒有逾時的非同步窺視作業。作業要等到訊息可以在佇列中使用之後才算完成。Initiates an asynchronous peek operation that has no time-out. The operation is not complete until a message becomes available in the queue.

public:
 IAsyncResult ^ BeginPeek();
public IAsyncResult BeginPeek ();
member this.BeginPeek : unit -> IAsyncResult
Public Function BeginPeek () As IAsyncResult

傳回

識別傳送的非同步要求的 IAsyncResultThe IAsyncResult that identifies the posted asynchronous request.

例外狀況

存取訊息佇列方法時發生錯誤。An error occurred when accessing a Message Queuing method.

範例

下列程式碼範例會建立名為 MyPeekCompleted的事件處理常式、將它附加至 PeekCompleted 事件處理常式委派,並呼叫 BeginPeek,以在位於 ".\myQueue" 路徑的佇列上起始非同步查看作業。The following code example creates an event handler named MyPeekCompleted, attaches it to the PeekCompleted event handler delegate, and calls BeginPeek to initiate an asynchronous peek operation on the queue that is located at the path ".\myQueue". 當引發 PeekCompleted 事件時,此範例會查看訊息,並將其主體寫入畫面。When a PeekCompleted event is raised, the example peeks the message and writes its body to the screen. 然後,此範例會再次呼叫 BeginPeek,以起始新的非同步查看作業。The example then calls BeginPeek again to initiate a new asynchronous peek operation.

#using <system.dll>
#using <system.messaging.dll>

using namespace System;
using namespace System::Messaging;

// This example performs asynchronous peek operation
// processing.
//*************************************************
ref class MyNewQueue
{
public:

   // Provides an event handler for the PeekCompleted
   // event.
   static void MyPeekCompleted( Object^ source, PeekCompletedEventArgs^ asyncResult )
   {
      // Connect to the queue.
      MessageQueue^ mq = dynamic_cast<MessageQueue^>(source);

      // End the asynchronous peek operation.
      Message^ m = mq->EndPeek( asyncResult->AsyncResult );

      // Display message information on the screen.
      Console::WriteLine( "Message: {0}", static_cast<String^>(m->Body) );

      // Restart the asynchronous peek operation.
      mq->BeginPeek();
      return;
   }
};

// Provides an entry point into the application.
//         
int main()
{
   // Create an instance of MessageQueue. Set its formatter.
   MessageQueue^ myQueue = gcnew MessageQueue( ".\\myQueue" );
   array<Type^>^p = gcnew array<Type^>(1);
   p[ 0 ] = String::typeid;
   myQueue->Formatter = gcnew XmlMessageFormatter( p );

   // Add an event handler for the PeekCompleted event.
   myQueue->PeekCompleted += gcnew PeekCompletedEventHandler( MyNewQueue::MyPeekCompleted );

   // Begin the asynchronous peek operation.
   myQueue->BeginPeek();

   // Do other work on the current thread.
   return 0;
}
using System;
using System.Messaging;

namespace MyProject
{
    /// <summary>
    /// Provides a container class for the example.
    /// </summary>
    public class MyNewQueue
    {

        //**************************************************
        // Provides an entry point into the application.
        //		 
        // This example performs asynchronous peek operation
        // processing.
        //**************************************************

        public static void Main()
        {
            // Create an instance of MessageQueue. Set its formatter.
            MessageQueue myQueue = new MessageQueue(".\\myQueue");
            myQueue.Formatter = new XmlMessageFormatter(new Type[]
                {typeof(String)});

            // Add an event handler for the PeekCompleted event.
            myQueue.PeekCompleted += new 
                PeekCompletedEventHandler(MyPeekCompleted);
            
            // Begin the asynchronous peek operation.
            myQueue.BeginPeek();
            
            // Do other work on the current thread.

            return;
        }


        //**************************************************
        // Provides an event handler for the PeekCompleted
        // event.
        //**************************************************
        
        private static void MyPeekCompleted(Object source, 
            PeekCompletedEventArgs asyncResult)
        {
            // Connect to the queue.
            MessageQueue mq = (MessageQueue)source;

            // End the asynchronous peek operation.
            Message m = mq.EndPeek(asyncResult.AsyncResult);

            // Display message information on the screen.
            Console.WriteLine("Message: " + (string)m.Body);

            // Restart the asynchronous peek operation.
            mq.BeginPeek();
            
            return; 
        }
    }
}
Imports System.Messaging





' Provides a container class for the example.
Public Class MyNewQueue



        ' Provides an entry point into the application.
        '		 
        ' This example performs asynchronous peek operation
        ' processing.


        Public Shared Sub Main()
            ' Create an instance of MessageQueue. Set its formatter.
            Dim myQueue As New MessageQueue(".\myQueue")
            myQueue.Formatter = New XmlMessageFormatter(New Type() _
                {GetType([String])})

            ' Add an event handler for the PeekCompleted event.
            AddHandler myQueue.PeekCompleted, AddressOf _
                MyPeekCompleted

            ' Begin the asynchronous peek operation.
            myQueue.BeginPeek()

            ' Do other work on the current thread.
            Return
        End Sub


        '**************************************************
        ' Provides an event handler for the PeekCompleted
        ' event.
        '**************************************************

        Private Shared Sub MyPeekCompleted(ByVal [source] As _
            [Object], ByVal asyncResult As PeekCompletedEventArgs)

            ' Connect to the queue.
            Dim mq As MessageQueue = CType([source], MessageQueue)

            ' End the asynchronous peek operation.
            Dim m As Message = mq.EndPeek(asyncResult.AsyncResult)

            ' Display message information on the screen.
            Console.WriteLine(("Message: " + CStr(m.Body)))

            ' Restart the asynchronous peek operation.
            mq.BeginPeek()

            Return

        End Sub

End Class

備註

在非同步處理中,您可以使用 BeginPeek,在佇列中有訊息可用時引發 PeekCompleted 事件。In asynchronous processing, you use BeginPeek to raise the PeekCompleted event when a message becomes available in the queue.

如果訊息已經存在於佇列中,也會引發 PeekCompletedPeekCompleted is also raised if a message already exists in the queue.

若要使用 BeginPeek,請建立一個事件處理常式來處理非同步作業的結果,並將它與您的事件委派產生關聯。To use BeginPeek, create an event handler that processes the results of the asynchronous operation, and associate it with your event delegate. BeginPeek 會起始非同步查看作業;當訊息抵達佇列時,會透過引發 PeekCompleted 事件來通知 MessageQueueBeginPeek initiates an asynchronous peek operation; the MessageQueue is notified, through the raising of the PeekCompleted event, when a message arrives in the queue. 然後 MessageQueue 可以藉由呼叫 EndPeek(IAsyncResult) 或藉由使用 PeekCompletedEventArgs來抓取結果,來存取訊息。The MessageQueue can then access the message by calling EndPeek(IAsyncResult) or by retrieving the result using the PeekCompletedEventArgs.

BeginPeek 方法會立即傳回,但是在呼叫事件處理常式之前,非同步作業不會完成。The BeginPeek method returns immediately, but the asynchronous operation is not completed until the event handler is called.

因為 BeginPeek 是非同步,所以您可以呼叫它來查看佇列,而不會封鎖目前執行的執行緒。Because BeginPeek is asynchronous, you can call it to peek the queue without blocking the current thread of execution. 若要同步查看佇列,請使用 Peek 方法。To synchronously peek the queue, use the Peek method.

非同步作業完成後,您可以在事件處理常式中再次呼叫 BeginPeekBeginReceive,以繼續接收通知。Once an asynchronous operation completes, you can call BeginPeek or BeginReceive again in the event handler to keep receiving notifications.

BeginPeek 傳回的 IAsyncResult 會識別方法啟動的非同步作業。The IAsyncResult that BeginPeek returns identifies the asynchronous operation that the method started. 雖然您通常不會在呼叫 EndPeek(IAsyncResult) 之前使用此 IAsyncResult,但您可以在作業的整個存留期間使用此。You can use this IAsyncResult throughout the lifetime of the operation, although you generally do not use it until EndPeek(IAsyncResult) is called. 不過,如果您啟動數個非同步作業,您可以將其 IAsyncResult 值放在陣列中,並指定是否要等候所有作業或任何作業完成。However, if you start several asynchronous operations, you can place their IAsyncResult values in an array and specify whether to wait for all operations or any operation to complete. 在此情況下,您可以使用 IAsyncResultAsyncWaitHandle 屬性來識別已完成的作業。In this case, you use the AsyncWaitHandle property of the IAsyncResult to identify the completed operation.

如果 falseCanRead,就會引發完成事件,但在呼叫 EndPeek(IAsyncResult)時,將會擲回例外狀況(exception)。If CanRead is false, the completion event is raised, but an exception will be thrown when calling EndPeek(IAsyncResult).

下表顯示這個方法是否可在各種工作組模式中使用。The following table shows whether this method is available in various Workgroup modes.

工作組模式Workgroup mode 可用Available
本機電腦Local computer Yes
本機電腦和直接格式名稱Local computer and direct format name Yes
遠端電腦Remote computer No
遠端電腦和直接格式名稱Remote computer and direct format name Yes

執行緒安全性

方法不是安全線程。The method is not thread safe.

另請參閱

BeginPeek(TimeSpan)

啟始有指定逾時的非同步窺視作業。在訊息可以於佇列中使用或發生逾時之後,作業才會完成。Initiates an asynchronous peek operation that has a specified time-out. The operation is not complete until either a message becomes available in the queue or the time-out occurs.

public:
 IAsyncResult ^ BeginPeek(TimeSpan timeout);
public IAsyncResult BeginPeek (TimeSpan timeout);
member this.BeginPeek : TimeSpan -> IAsyncResult
Public Function BeginPeek (timeout As TimeSpan) As IAsyncResult

參數

timeout
TimeSpan

TimeSpan,指出等待訊息變成可以使用的時間間隔。A TimeSpan that indicates the interval of time to wait for a message to become available.

傳回

識別傳送的非同步要求的 IAsyncResultThe IAsyncResult that identifies the posted asynchronous request.

例外狀況

指定給 timeout 參數的值無效。The value specified for the timeout parameter is not valid.

存取訊息佇列方法時發生錯誤。An error occurred when accessing a Message Queuing method.

範例

下列程式碼範例會使用佇列路徑 ".\myQueue" 來建立非同步查看作業。The following code example creates an asynchronous peek operation, using the queue path ".\myQueue". 它會建立事件處理常式 MyPeekCompleted,並將它附加至 PeekCompleted 事件處理常式委派。It creates an event handler, MyPeekCompleted, and attaches it to the PeekCompleted event handler delegate. 會以一分鐘的時間來呼叫 BeginPeek,以起始非同步查看作業。BeginPeek is called with a time-out of one minute, to initiate the asynchronous peek operation. PeekCompleted 事件引發或過期時,會抓取訊息(如果有的話),並將其主體寫入畫面。When a PeekCompleted event is raised or the time-out expires, the message is retrieved if one exists, and its body is written to the screen. 然後再次呼叫 BeginPeek,以使用相同的超時時間來起始新的非同步查看作業。Then BeginPeek is called again to initiate a new asynchronous peek operation with the same time-out.

#using <system.dll>
#using <system.messaging.dll>

using namespace System;
using namespace System::Messaging;
ref class MyNewQueue
{
public:
   static void MyPeekCompleted( Object^ source, PeekCompletedEventArgs^ asyncResult )
   {      try
      {
         // Connect to the queue.
         MessageQueue^ mq = dynamic_cast<MessageQueue^>(source);

         // End the asynchronous peek operation.
         Message^ m = mq->EndPeek( asyncResult->AsyncResult );

         // Display message information on the screen.
         Console::WriteLine( "Message: {0}", static_cast<String^>(m->Body) );

         // Restart the asynchronous peek operation, with the 
         // same time-out.
         mq->BeginPeek( TimeSpan(0,1,0) );
      }
      catch ( MessageQueueException^ e ) 
      {
         if ( e->MessageQueueErrorCode == MessageQueueErrorCode::IOTimeout )
         {
            Console::WriteLine( e );
         }

         // Handle other sources of MessageQueueException.
      }

      // Handle other exceptions.
      return;
   }
};

int main()
{
   // Create an instance of MessageQueue. Set its formatter.
   MessageQueue^ myQueue = gcnew MessageQueue( ".\\myQueue" );
   array<Type^>^p = gcnew array<Type^>(1);
   p[ 0 ] = String::typeid;
   myQueue->Formatter = gcnew XmlMessageFormatter( p );

   // Add an event handler for the PeekCompleted event.
   myQueue->PeekCompleted += gcnew PeekCompletedEventHandler( MyNewQueue::MyPeekCompleted );

   // Begin the asynchronous peek operation with a timeout 
   // of one minute.
   myQueue->BeginPeek( TimeSpan(0,1,0) );

   // Do other work on the current thread.
   return 0;
}
using System;
using System.Messaging;

namespace MyProject
{
    /// <summary>
    /// Provides a container class for the example.
    /// </summary>
    public class MyNewQueue
    {

        //**************************************************
        // Provides an entry point into the application.
        //		 
        // This example performs asynchronous peek operation
        // processing.
        //**************************************************

        public static void Main()
        {
            // Create an instance of MessageQueue. Set its formatter.
            MessageQueue myQueue = new MessageQueue(".\\myQueue");
            myQueue.Formatter = new XmlMessageFormatter(new Type[]
                {typeof(String)});

            // Add an event handler for the PeekCompleted event.
            myQueue.PeekCompleted += new 
                PeekCompletedEventHandler(MyPeekCompleted);
            
            // Begin the asynchronous peek operation with a time-out 
            // of one minute.
            myQueue.BeginPeek(new TimeSpan(0,1,0));
            
            // Do other work on the current thread.

            return;
        }


        //**************************************************
        // Provides an event handler for the PeekCompleted
        // event.
        //**************************************************
        
        private static void MyPeekCompleted(Object source, 
            PeekCompletedEventArgs asyncResult)
        {
            try
            {
                // Connect to the queue.
                MessageQueue mq = (MessageQueue)source;

                // End the asynchronous peek operation.
                Message m = mq.EndPeek(asyncResult.AsyncResult);

                // Display message information on the screen.
                Console.WriteLine("Message: " + (string)m.Body);

                // Restart the asynchronous peek operation, with the 
                // same time-out.
                mq.BeginPeek(new TimeSpan(0,1,0));

            }

            catch(MessageQueueException e)
            {
                if (e.MessageQueueErrorCode == 
                    MessageQueueErrorCode.IOTimeout)
                {
                    Console.WriteLine(e.ToString());
                }

                // Handle other sources of MessageQueueException.
            }
            
            // Handle other exceptions.
            
            return; 
        }
    }
}
Imports System.Messaging


' Provides a container class for the example.
Public Class MyNewQueue



        ' Provides an entry point into the application.
        '		 
        ' This example performs asynchronous peek operation
        ' processing.


        Public Shared Sub Main()
            ' Create an instance of MessageQueue. Set its formatter.
            Dim myQueue As New MessageQueue(".\myQueue")
            myQueue.Formatter = New XmlMessageFormatter(New Type() _
                    {GetType([String])})

            ' Add an event handler for the PeekCompleted event.
            AddHandler myQueue.PeekCompleted, _
                    AddressOf MyPeekCompleted

            ' Begin the asynchronous peek operation with a time-out 
            ' of one minute.
            myQueue.BeginPeek(New TimeSpan(0, 1, 0))

            ' Do other work on the current thread.
            Return

        End Sub



        ' Provides an event handler for the PeekCompleted
        ' event.


        Private Shared Sub MyPeekCompleted(ByVal [source] As _
            [Object], ByVal asyncResult As _
            PeekCompletedEventArgs)

            Try
                ' Connect to the queue.
                Dim mq As MessageQueue = CType([source], _
                    MessageQueue)

                ' End the asynchronous peek operation.
                Dim m As Message = _
                    mq.EndPeek(asyncResult.AsyncResult)

                ' Display message information on the screen.
                Console.WriteLine(("Message: " + CStr(m.Body)))

                ' Restart the asynchronous peek operation, with the 
                ' same time-out.
                mq.BeginPeek(New TimeSpan(0, 1, 0))

            Catch e As MessageQueueException

                If e.MessageQueueErrorCode = _
                    MessageQueueErrorCode.IOTimeout Then

                    Console.WriteLine(e.ToString())

                    ' Handle other sources of MessageQueueException.
                End If

                ' Handle other exceptions.

            End Try

            Return

        End Sub

End Class

備註

在非同步處理中,您可以使用 BeginPeek 在佇列中有訊息可供使用時,或指定的時間間隔已過期時,引發 PeekCompleted 事件。In asynchronous processing, you use BeginPeek to raise the PeekCompleted event when a message becomes available in the queue or when the specified interval of time has expired.

如果訊息已經存在於佇列中,也會引發 PeekCompletedPeekCompleted is also raised if a message already exists in the queue.

若要使用 BeginPeek,請建立一個事件處理常式來處理非同步作業的結果,並將它與您的事件委派產生關聯。To use BeginPeek, create an event handler that processes the results of the asynchronous operation, and associate it with your event delegate. BeginPeek 會起始非同步查看作業;當訊息抵達佇列時,會透過引發 PeekCompleted 事件來通知 MessageQueueBeginPeek initiates an asynchronous peek operation; the MessageQueue is notified, through the raising of the PeekCompleted event, when a message arrives in the queue. 然後 MessageQueue 可以藉由呼叫 EndPeek(IAsyncResult) 或藉由使用 PeekCompletedEventArgs來抓取結果,來存取訊息。The MessageQueue can then access the message by calling EndPeek(IAsyncResult) or by retrieving the result using the PeekCompletedEventArgs.

BeginPeek 方法會立即傳回,但是在呼叫事件處理常式之前,非同步作業不會完成。The BeginPeek method returns immediately, but the asynchronous operation is not completed until the event handler is called.

因為 BeginPeek 是非同步,所以您可以呼叫它來查看佇列,而不會封鎖目前執行的執行緒。Because BeginPeek is asynchronous, you can call it to peek the queue without blocking the current thread of execution. 若要同步查看佇列,請使用 Peek 方法。To synchronously peek the queue, use the Peek method.

非同步作業完成後,您可以在事件處理常式中再次呼叫 BeginPeekBeginReceive,以繼續接收通知。Once an asynchronous operation completes, you can call BeginPeek or BeginReceive again in the event handler to keep receiving notifications.

BeginPeek 傳回的 IAsyncResult 會識別方法啟動的非同步作業。The IAsyncResult that BeginPeek returns identifies the asynchronous operation that the method started. 雖然您通常不會在呼叫 EndPeek(IAsyncResult) 之前使用此 IAsyncResult,但您可以在作業的整個存留期間使用此。You can use this IAsyncResult throughout the lifetime of the operation, although you generally do not use it until EndPeek(IAsyncResult) is called. 不過,如果您啟動數個非同步作業,您可以將其 IAsyncResult 值放在陣列中,並指定是否要等候所有作業或任何作業完成。However, if you start several asynchronous operations, you can place their IAsyncResult values in an array and specify whether to wait for all operations or any operation to complete. 在此情況下,您可以使用 IAsyncResultAsyncWaitHandle 屬性來識別已完成的作業。In this case, you use the AsyncWaitHandle property of the IAsyncResult to identify the completed operation.

這個多載會指定超時時間。如果 timeout 參數所指定的間隔過期,這個元件就會引發 PeekCompleted 事件。This overload specifies a time-out. If the interval specified by the timeout parameter expires, this component raises the PeekCompleted event. 因為不存在任何訊息,後續對 EndPeek(IAsyncResult) 的呼叫將會擲回例外狀況。Because no message exists, a subsequent call to EndPeek(IAsyncResult) will throw an exception.

如果 falseCanRead,就會引發完成事件,但在呼叫 EndPeek(IAsyncResult)時,將會擲回例外狀況(exception)。If CanRead is false, the completion event is raised, but an exception will be thrown when calling EndPeek(IAsyncResult).

下表顯示這個方法是否可在各種工作組模式中使用。The following table shows whether this method is available in various Workgroup modes.

工作組模式Workgroup mode 可用Available
本機電腦Local computer Yes
本機電腦和直接格式名稱Local computer and direct format name Yes
遠端電腦Remote computer No
遠端電腦和直接格式名稱Remote computer and direct format name Yes

執行緒安全性

方法不是安全線程。The method is not thread safe.

另請參閱

適用於