MessageQueue.Peek メソッド (TimeSpan)

[アーティクル]
03/28/2008

この MessageQueue が参照するキューにある最初のメッセージを、削除せずに返します (ピークします)。 Peek メソッドは同期メソッドであるため、メッセージが利用可能になるか、指定したタイムアウトが発生するまで、現在のスレッドをブロックします。

Overloads Public Function Peek( _
   ByVal timeout As TimeSpan _) As Message
[C#]
public Message Peek(TimeSpantimeout);
[C++]
public: Message* Peek(TimeSpantimeout);
[JScript]
public function Peek(
   timeout : TimeSpan) : Message;

パラメータ

timeout
キューにメッセージが格納されるまで待機する最大時間を示す TimeSpan 。

戻り値

キューの最初のメッセージを表す Message 。

例外

例外の種類	条件
ArgumentException	timeout パラメータに指定した値が不正です。 timeout が TimeSpan.Zero よりも小さいか、 TimeSpan.MaxValue よりも大きい可能性があります。
MessageQueueException	メッセージキューの API にアクセスしたときにエラーが発生しました。

解説

このオーバーロードを使用して、キューをピークしたり、キューにメッセージが到達するまで指定した時間待機したりします。メッセージが既にキューに存在する場合、このメソッドからすぐに制御が戻ります。

Peek メソッドは、最初のメッセージをキューから読み取りますが、削除はしません。そのため、 Peek を繰り返し呼び出すと、より優先順位の高いメッセージがそのキューに到達するまで、同じメッセージが返されます。一方、 Receive メソッドは、最初のメッセージをキューから読み取り、削除します。そのため、 Receive を繰り返し呼び出すと、異なるメッセージが返されます。

メモメッセージキューは、優先順位と到達時刻に従って、メッセージをキューの中で並べ替えます。新しいメッセージは、優先順位が高い場合にだけ、古いメッセージの前に置かれます。

キューにメッセージが到達するまで待機する間、現在のスレッドがブロックされてもいい場合は、 Peek を使用します。スレッドは、指定した時間までブロックされます。 InfiniteTimeout 値を指定した場合は、無期限にブロックされます。待機せずにアプリケーションの処理を継続する必要がある場合は、非同期の BeginPeek メソッドを使用します。

このメソッドが各種のワークグループモードで使用できるかどうかを次の表に示します。

ワークグループモード	使用可否
ローカルコンピュータ	はい
ローカルコンピュータ + 直接書式名	はい
リモートコンピュータ	いいえ
リモートコンピュータ + 直接書式名	はい

使用例

[Visual Basic, C#, C++] タイムアウトが 0 の Peek メソッドを使用して、キューが空かどうかを確認する例を次に示します。

 
Imports System
Imports 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 determines whether a queue is empty.
        '**************************************************

        Public Shared Sub Main()

            ' Create a new instance of the class.
            Dim myNewQueue As New MyNewQueue()

            ' Determine whether a queue is empty.
            Dim isQueueEmpty As Boolean = myNewQueue.IsQueueEmpty()

            Return

        End Sub 'Main


        '**************************************************
        ' Determines whether a queue is empty. The Peek()
        ' method throws an exception if there is no message
        ' in the queue. This method handles that exception 
        ' by returning true to the calling method.
        '**************************************************

        Public Function IsQueueEmpty() As Boolean

            Dim queueEmpty As Boolean = False

            ' Connect to a queue.
            Dim myQueue As New MessageQueue(".\myQueue")

            Try

                ' Set Peek to return immediately.
                myQueue.Peek(New TimeSpan(0))

                ' If an IOTimeout was not thrown, there is a message 
                ' in the queue.
                queueEmpty = False

            Catch e As MessageQueueException

                If e.MessageQueueErrorCode = _
                    MessageQueueErrorCode.IOTimeout Then

                    ' No message was in the queue.
                    IsQueueEmpty = True

                End If

                ' Handle other sources of MessageQueueException as necessary.

                ' Handle other exceptions as necessary.

            End Try

            ' Return true if there are no messages in the queue.
            Return queueEmpty

        End Function 'IsQueueEmpty 

    End Class 'MyNewQueue
End Namespace 'MyProject

[C#] 
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 determines whether a queue is empty.
        //**************************************************

        public static void Main()
        {
            // Create a new instance of the class.
            MyNewQueue myNewQueue = new MyNewQueue();

            // Determine whether a queue is empty.
            bool isQueueEmpty = myNewQueue.IsQueueEmpty();
                        
            return;
        }


        //**************************************************
        // Determines whether a queue is empty. The Peek()
        // method throws an exception if there is no message
        // in the queue. This method handles that exception 
        // by returning true to the calling method.
        //**************************************************
        
        public bool IsQueueEmpty()
        {
            bool isQueueEmpty = false;

            // Connect to a queue.
            MessageQueue myQueue = new MessageQueue(".\\myQueue");

            try
            {
                // Set Peek to return immediately.
                myQueue.Peek(new TimeSpan(0));

                // If an IOTimeout was not thrown, there is a message 
                // in the queue.
                isQueueEmpty = false;
            }

            catch(MessageQueueException e)
            {
                if (e.MessageQueueErrorCode == 
                    MessageQueueErrorCode.IOTimeout)
                {
                    // No message was in the queue.
                    isQueueEmpty = true;
                }

                // Handle other sources of MessageQueueException.
            }

            // Handle other exceptions as necessary.

            // Return true if there are no messages in the queue.
            return isQueueEmpty;

        }
    }
}

[C++] 
#using <mscorlib.dll>
#using <system.dll>
#using <system.messaging.dll>

using namespace System;
using namespace System::Messaging;

__gc class MyNewQueue
{
    //*************************************************
    // Determines whether a queue is empty. The Peek()
    // method throws an exception if there is no message
    // in the queue. This method handles that exception 
    // by returning true to the calling method.
    //*************************************************
public:
    bool IsQueueEmpty() 
    {
        bool isQueueEmpty = false;

        // Connect to a queue.
        MessageQueue* myQueue = new MessageQueue(S".\\myQueue");

        try 
        {
            // Set Peek to return immediately.
            myQueue->Peek(TimeSpan(0));

            // If an IOTime->Item[Out] was* not thrown, there is a message 
            // in the queue.
            isQueueEmpty = false;
        }
        catch (MessageQueueException* e) 
        {
            if (e->MessageQueueErrorCode == 
                MessageQueueErrorCode::IOTimeout) 
            {
                // No message was in the queue.
                isQueueEmpty = true;
            }

            // Handle other sources of MessageQueueException.
        }

        // Handle other exceptions as necessary.

        // Return true if there are no messages in the queue.
        return isQueueEmpty;
    }
};

//*************************************************
// Provides an entry point into the application.
//         
// This example determines whether a queue is empty.
//*************************************************

int main() 
{
    // Create a new instance of the class.
    MyNewQueue* myNewQueue = new MyNewQueue();

    // Determine whether a queue is empty.
    bool isQueueEmpty = myNewQueue->IsQueueEmpty();

    return 0;
}

[JScript] JScript のサンプルはありません。Visual Basic、C#、および C++ のサンプルを表示するには、このページの左上隅にある言語のフィルタボタンをクリックします。

必要条件

プラットフォーム: Windows 98, Windows NT 4.0, Windows Millennium Edition, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003 ファミリ

.NET Framework セキュリティ:

直前の呼び出し元の完全信頼。このメンバは、部分的に信頼されているコードから使用することはできません。詳細の参照先 : 部分信頼コードからのライブラリの使用

参照

次の方法で共有

MessageQueue.Peek メソッド (TimeSpan)

パラメータ

戻り値

例外

解説

使用例

必要条件

参照

その他のリソース