Click or drag to resize
ZenophSMSgetBatchSubmitMax Method
Gets the maximum number of destinations that can be submitted to the SMS server at once which will immediately return the submit status for the destinations.

Namespace: Zenoph.SMSLib
Assembly: Zenoph.SMSLib (in Zenoph.SMSLib.dll) Version: 2015.9.30.0 (2015.09.30.0)
Syntax
public static int getBatchSubmitMax()

Return Value

Type: Int32
Returns the maximum number of destinations that can be submitted to the SMS server at once which will return the submit status for each destination.
Remarks

When a message is submitted, the SMS server checks the total number of destinations submitted. If the total number of destinations is greater than the value that this method returns, the server immediately returns a token and then begins submitting the message to those destinations. The returned token can be used to query the submit status of the destinations. The reason for this is to avoid the case when the caller will have to wait for a long time for the submit status when a lot of destinations are submitted to the SMS server. However, if the total number of destinations is less than or equal to the maximum value which is returned by this method, the SMS server will rather submit the message immediately and return with the submit status for each destination.

The importance of this method call comes when there are a lot of destinations to be submitted and there is the need to obtain the submit status for each destination immediately. In that case, the addition of destinations should be done in an iteration while also comparing the total destinations added (by calling getRecipientsCount) with the maximum batch submit returned from this method call. If the total number of destintions exactly equals the maximum batch submit value, then the message should be submitted and the destinations list cleared with a call to clearRecipients. The iteration will run until all destinations are added for submission.

The maximum number of destinations for a batch submit to return the submit status of the destinations should not be considered as a fixed value. Although by default this is set to 400, it is highly recommended that applications do not rely on this value since it is loaded from the server during authentication and thus could be dynamic. However, applications can expect that the submit status of the destinations will be immediately submitted if the total number of destinations is less than or equal to 300.

Examples
The following code demonstrates the use of this method when there are a lot of destinations to submit the message to. The idea is to determine when the total number of destinations added has reached the maximum submission value that will return the submit status of the destinations so that the added destinations can be submitted before adding the remaining ones for submission.
// Initialise SMS object and perform authentication.
ZenophSMS sms = new ZenophSMS();
sms.setUser("account_login");
sms.setPassword("account_password");
sms.authenticate();

sms.setMessage("Hello there!");
sms.setSenderId("SMSTEST");

/*
 * Now suppose we have a lot of destinations (about 500) in a list which needs to be added
 * and that we will want the SMS server to immediately return the submit status of each
 * destination. Then while adding the destination in an iteration, we will also check for
 * the total destinations against the maximum submit value. When we have reached the maximum
 * value, we will need to submit the added destinations, clear the list, and add the rest for submission.
 */
 List<string> numbers = sms.extractPhoneNumbers("string containing phone numbers");
  numbers.Add("+233241999999");

 List<string[]> resp = null;

 // suppose now that numbers list contains a lot of phone numbers
 // that the message will be submitted to.
 foreach (string phonenum in numbers)
 {
     // Add phone number. Iteration will not be terminated if phonenum is invalid or
     // not allowed on route since the second parameter is set to true.
     sms.addRecipient(phonenum, true);

     if (sms.getRecipientsCount() == ZenophSMS.getBatchSubmitMax())  // if maximum reached.
     {
         resp = sms.submit();    // submit and obtain the submit status.
         sms.clearRecipients();  // required to clear the destinations that were submitted.

         // if there is the need to process or show the submit status of the destinations
         // they can be acessed in the string array with the submit status in the first index
         // and the phone number in the second index. See example on discussion on submit() method.
         foreach (string[] state in resp)
             Console.WriteLine(string.Format("Phone number: {0},  Status: {1}", state[1], state[0]));
     }
 }

 // submit the remaining and obtain the submit status.
 resp = sms.submit();

From the above code example, the aim was to immediately obtain submit status after submission to the SMS server hence the need to ensure that if the total destinations added has reached the maximum submission value for which submit status would be returned immediately, then the destinations are submitted and the rest added for submission until all are sent. If this check is not done and the total destinations added is greater than the value returned from this method call, the SMS server will immediately return a token and proceed with the submission so that the returned token can be used to query the submit status of the destinations later.

See Also