| Customize Help

Using .NET strings with MIL


Strings are handled differently in managed code than in unmanaged code. In managed code, strings are immutable (read-only) objects. Some MIL functions, such as M...Inquire() or M...GetResult(), have a parameter that requires a pointer to a modifiable string. Since strings are immutable in .NET, additional steps must be taken to use these functions. In these cases, you must create a StringBuilder object, and pass that StringBuilder object, rather than a pointer to a string, to the MIL function. The following example demonstrates how this is done.

using System.Text;
using Matrox.MatroxImagingLibrary;

namespace StringsWithMIL.SingleString
{
    class MyDigitizer
    {
        private MIL_ID _digId = MIL.M_NULL;

        public MyDigitizer(MIL_ID ownerSystem)
        {
            // Allocate the default digitizer on the specified system.
            MIL.MdigAlloc(ownerSystem, MIL.M_DEFAULT, "M_DEFAULT", MIL.M_DEFAULT, ref _digId);
        }

        public string Format
        {
            get
            {
                // Initialize a new StringBuilder object.
                // MIL will resize it to the appropriate size.
                StringBuilder format = new StringBuilder();
                MIL.MdigInquire(_digId, MIL.M_FORMAT, format);

                // Use the ToString method to return a string from the StringBuilder object.
                return format.ToString();
            }
        }
    }
}

When the call to the MIL function returns, the StringBuilder object contains a sequence of characters that ends with a null terminating character ('\0'). Then, you can retrieve the string object by calling the ToString function of the StringBuilder instance.

If the M...Inquire() or M...GetResult() function returns multiple strings separated by null terminating characters, the StringBuilder object cannot be used, since it would return only the first string. In this case, you have to get the strings in an array of characters. When the call to the MIL function returns, you can then parse the character array into an array of strings as shown in the example below.

using System.Text;
using Matrox.MatroxImagingLibrary;

namespace StringsWithMIL.MultipleStrings
{
    class MyDigitizer
    {
        private MIL_ID _digId = MIL.M_NULL;

        public MyDigitizer(MIL_ID ownerSystem)
        {
            // Allocate the default digitizer on the specified system.
            MIL.MdigAlloc(ownerSystem, MIL.M_DEFAULT, "M_DEFAULT", MIL.M_DEFAULT, ref _digId);
        }

        public string[] SupportedFormats
        {
            get
            {
                // Get the number of formats supported.
                MIL_INT numberOfFormats = 
                  MIL.MdigInquire(_digId, MIL.M_FORMAT_SUPPORTED_NUM, MIL.M_NULL);

                // Get the size of a supported format.
                MIL_INT formatLength = 
                  MIL.MdigInquire(_digId, MIL.M_FORMAT_SUPPORTED + MIL.M_STRING_SIZE, MIL.M_NULL);

                // Get the supported formats as an array of characters.
                char[] formatCharacters = new char[numberOfFormats * formatLength];
                MIL.MdigInquire(_digId, MIL.M_FORMAT_SUPPORTED, formatCharacters);

                string[] supportedFormats = new string[numberOfFormats];
                for (int i = 0; i < supportedFormats.Length; i++)
                {
                  // Each format string has 'formatLength' characters and is null terminated.
                    supportedFormats[i] = 
                     new string(formatCharacters, i * (int)formatLength, (int)formatLength);
                }

                return supportedFormats;
            }
        }
    }
}